इवेंट मैनेज करना

इस पेज पर, चार्ट से सक्रिय होने वाले इवेंट को सुनने और मैनेज करने का तरीका बताया गया है.

विषय सूची

खास जानकारी

Google चार्ट ऐसे इवेंट चालू कर सकते हैं जिन्हें सुना जा सकता है. इवेंट को उपयोगकर्ता की कार्रवाइयों से ट्रिगर किया जा सकता है, जैसे कि जब कोई उपयोगकर्ता किसी चार्ट पर क्लिक करता है. JavaScript इवेंट को रजिस्टर किया जा सकता है, ताकि किसी खास इवेंट के सक्रिय होने पर उसे कॉल किया जा सके. खास इवेंट में किसी खास इवेंट से जुड़े डेटा का इस्तेमाल किया जा सकता है.

हर चार्ट अपने इवेंट के बारे में बताता है. साथ ही, उस चार्ट के दस्तावेज़ में यह बताया जाना चाहिए कि हर इवेंट को कब ट्रिगर किया जाता है, उसका क्या मतलब होता है, और इवेंट से जुड़ी किसी भी तरह की जानकारी कैसे मिलेगी. इस पेज पर बताया गया है कि चार्ट से इवेंट पाने के लिए कैसे रजिस्टर किया जा सकता है और उन्हें कैसे मैनेज किया जा सकता है.

एक ऐसा इवेंट होता है जिसे चुनने लायक किसी भी चार्ट को सक्रिय करना चाहिए: वह इवेंट चुनें. हालांकि, इस इवेंट का व्यवहार और मतलब हर चार्ट से तय होता है.

ध्यान दें कि चार्ट इवेंट, स्टैंडर्ड डीओएम इवेंट से अलग और अलग होते हैं.

इवेंट को रजिस्टर और मैनेज करना

अपने इवेंट हैंडलर रजिस्टर करने के लिए, आप google.visualization.events.addListener() या addOneTimeListener() को कॉल करते हैं. इवेंट के बारे में जानकारी देने वाले चार्ट का नाम, उसे सुनने के लिए इवेंट का स्ट्रिंग, और इवेंट के सक्रिय होने पर कॉल करने के लिए फ़ंक्शन का नाम कहते हैं. आपके फ़ंक्शन को एक ऐसा पैरामीटर स्वीकार करना चाहिए जो सक्रिय किया गया इवेंट हो. इस इवेंट में, इवेंट के बारे में कस्टम जानकारी दी जा सकती है, जैसा कि चार्ट में दस्तावेज़ में बताया गया है.

अहम जानकारी: अगर आपके चार्ट में पहले से तैयार इवेंट दिखता है, तो चार्ट में इवेंट जोड़ने या आपको उससे जुड़ी जानकारी भेजने से पहले, आपको इवेंट के चलने का इंतज़ार करना होगा. हो सकता है कि ये चार्ट, पहले से तैयार इवेंट को शामिल करने से पहले काम करें, लेकिन इस बात की कोई गारंटी नहीं है कि यह सही होगा या नहीं.

जब भी उपयोगकर्ता किसी टेबल की पंक्ति पर क्लिक करता है, तब नीचे दिए गए कोड स्निपेट में एक चेतावनी बॉक्स दिखता है:

// Create a table chart on your page.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

// Every time the table fires the "select" event, it should call your
// selectHandler() function.
google.visualization.events.addListener(table, 'select', selectHandler);

function selectHandler(e) {
  alert('A table row was selected');
}

ध्यान दें कि यह सिर्फ़ इस खास टेबल ऑब्जेक्ट के इवेंट सुनने के लिए रजिस्टर करेगा. आप सिर्फ़ किसी खास ऑब्जेक्ट के इवेंट पाने के लिए रजिस्टर कर सकते हैं.

आप कोई फ़ंक्शन परिभाषा भी पास कर सकते हैं, जैसा कि यहां दिखाया गया है:

// Pass in a function definition.
google.visualization.events.addListener(orgchart, 'select', function() {
  table.setSelection(orgchart.getSelection());
});

इवेंट की जानकारी पाना

आम तौर पर, इवेंट दो तरह से जानकारी दिखाते हैं: पैरामीटर के तौर पर हैंडलर फ़ंक्शन में जानकारी पास करके या ग्लोबल ऑब्जेक्ट में जानकारी जोड़कर. इवेंट के बारे में जानकारी देने और अगर जानकारी देने का तरीका, उस चार्ट के दस्तावेज़ में बताया जाना चाहिए. दोनों तरह की जानकारी वापस पाने का तरीका:

आपके हैंडलर को भेजी गई इवेंट की जानकारी

अगर चार्ट, आपके हैंडलिंग फ़ंक्शन में पैरामीटर के तौर पर डेटा पास करता है, तो आपको उसे यहां दिखाए गए तरीके से फिर से हासिल करना होगा:

// google.visualization.table exposes a 'page' event.
google.visualization.events.addListener(table, 'page', myPageEventHandler);
...
function myPageEventHandler(e) {
  alert('The user is navigating to page ' + e['page']);
}

आपके हैंडलर में दिए गए पैरामीटर में एक ऐसी प्रॉपर्टी होगी जिसे चार्ट के लिए दस्तावेज़ में जोड़ा जाना चाहिए. इस तरह के इवेंट की जानकारी दिखाने वाले चार्ट का उदाहरण देखने के लिए, टेबल चार्ट का पेज इवेंट देखें.

किसी ग्लोबल ऑब्जेक्ट को भेजी गई इवेंट की जानकारी

इसके बजाय, कुछ इवेंट, ग्लोबल ऑब्जेक्ट की प्रॉपर्टी बदल देते हैं. इसके बाद, आप इसका अनुरोध कर सकते हैं. इसका एक सामान्य उदाहरण "चुनें" इवेंट है. यह तब ट्रिगर होता है, जब कोई उपयोगकर्ता चार्ट के किसी हिस्से को चुनता है. इस मामले में, मौजूदा चुने गए विकल्प को जानने के लिए, कोड चार्ट पर getSelection() को कॉल करना चाहिए. नीचे चुने गए इवेंट के बारे में ज़्यादा जानकारी दी गई है.

// orgChart is my global orgchart chart variable.
google.visualization.events.addListener(orgChart, 'select', selectHandler);
...
// Notice that e is not used or needed.
function selectHandler(e) {
  alert('The user selected' + orgChart.getSelection().length + ' items.');
  

select इवेंट

जैसा कि पहले बताया गया है, अगर किसी चार्ट को चुना जाता है, तो उसे ऐसे "चुनें" इवेंट को सक्रिय करना चाहिए जो स्टैंडर्ड तरीके से काम करता है. इससे आपको चार्ट में चुने गए आइटम की वैल्यू फिर से पाने में मदद मिलती है. (हालांकि, इस बात की कोई ज़रूरी शर्त नहीं है कि चार्ट इसी तरह से व्यवहार करे; अपने चार्ट के लिए दस्तावेज़ देखें).

आम तौर पर, "चुनें" इवेंट को दिखाने वाले चार्ट, इन खास बातों के साथ डिज़ाइन किए जाते हैं:

  • चुना गया इवेंट हैंडलर में कोई भी प्रॉपर्टी या ऑब्जेक्ट पास नहीं करता है (आपके फ़ंक्शन हैंडलर को किसी भी पैरामीटर के पास होने की उम्मीद नहीं करनी चाहिए).
  • चार्ट को तरीका getSelection() दिखाना चाहिए, जिससे चुने गए डेटा एलिमेंट के बारे में बताने वाली कई ऑब्जेक्ट मिलती हैं. इन ऑब्जेक्ट में row और column प्रॉपर्टी होती हैं. row और column, DataTable में चुने गए आइटम की पंक्ति और कॉलम इंडेक्स हैं. (चुने गए इवेंट, ग्राफ़ में दिए गए डेटा के बारे में बताते हैं, न कि चार्ट में मौजूद एचटीएमएल एलिमेंट की.) चुने गए आइटम का डेटा पाने के लिए, आपको DataTable.getValue() या getFormattedValue() को कॉल करना होगा.
    अगर row और column, दोनों के बारे में बताया गया है, तो चुना गया एलिमेंट एक सेल है. अगर सिर्फ़ row तय किया गया है, तो चुना गया एलिमेंट एक पंक्ति है. अगर सिर्फ़ column तय किया गया है, तो चुना गया एलिमेंट एक कॉलम है.
  • चुने गए टेबल में चुने गए विकल्प को बदलने और उससे जुड़े डेटा को चार्ट में चुनने के लिए, चार्ट में setSelection(selection) तरीका दिखाया जाना चाहिए. selection पैरामीटर, getSelection() अरे के जैसी श्रेणी है, जहां हर एलिमेंट एक ऑब्जेक्ट है, जिसमें row और column प्रॉपर्टी हैं. row प्रॉपर्टी की मदद से, DataTable में चुनी गई पंक्ति के इंडेक्स के बारे में बताया जाता है. साथ ही, column प्रॉपर्टी की मदद से, DataTable में चुने गए कॉलम का इंडेक्स तय किया जाता है. इस तरीके को कॉल करने पर, चार्ट में विज़ुअल तौर पर यह बताया जाना चाहिए कि नया विकल्प क्या है. setSelection() को लागू करने पर, 'select' इवेंट को ट्रिगर नहीं करना चाहिए.
    अगर row और column, दोनों के बारे में बताया गया है, तो चुना गया एलिमेंट एक सेल है. अगर सिर्फ़ row तय किया गया है, तो चुना गया एलिमेंट एक पंक्ति है. अगर सिर्फ़ column तय किया गया है, तो चुना गया एलिमेंट एक कॉलम है.

कुछ चेतावनियां:

  • चार्ट, चुने गए हिस्से को अनदेखा कर सकता है. उदाहरण के लिए, सिर्फ़ चुनी गई लाइनें दिखाने वाली टेबल, setSelection को लागू करने पर, सेल या कॉलम के एलिमेंट को अनदेखा कर सकती है.)
  • कुछ चार्ट, 'चुनें' इवेंट को ट्रिगर नहीं कर सकते. साथ ही, कुछ चार्ट सिर्फ़ पंक्ति को चुनने या पूरे कॉलम को चुनने का विकल्प दिखा सकते हैं. हर चार्ट के दस्तावेज़ में इसके इस्तेमाल होने वाले इवेंट और तरीकों के बारे में बताया गया है.
  • एक से ज़्यादा चुनने की सुविधा को अलग-अलग चार्ट में अलग-अलग तरह से मैनेज किया जाता है. कुछ चार्ट में इसकी अनुमति भी नहीं है.
  • चुने गए डेटा को पढ़ने के लिए, आपको अपने हैंडलर में DataTable.getValue() को कॉल करना होगा. इसके लिए, DataTable ऑब्जेक्ट को ग्लोबल बनाना सबसे आसान तरीका है.

टेबल चार्ट के किसी एलिमेंट को चुनने पर, इस उदाहरण में चुने गए टेबल एलिमेंट के साथ सूचना बॉक्स को पॉप अप किया जाता है:

ध्यान दें कि टेबल चार्ट सिर्फ़ पंक्ति चुनने के इवेंट चालू करता है. हालांकि, कोड सामान्य होता है और इसका इस्तेमाल पंक्ति, कॉलम, और सेल चुनने के इवेंट के लिए किया जा सकता है.

इस उदाहरण के लिए हैंडलर कोड यहां दिया गया है:

// Create our table.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, options);

// Add our selection handler.
google.visualization.events.addListener(table, 'select', selectHandler);

// The selection handler.
// Loop through all items in the selection and concatenate
// a single message from all of them.
function selectHandler() {
  var selection = table.getSelection();
  var message = '';
  for (var i = 0; i < selection.length; i++) {
    var item = selection[i];
    if (item.row != null && item.column != null) {
      var str = data.getFormattedValue(item.row, item.column);
      message += '{row:' + item.row + ',column:' + item.column + '} = ' + str + '\n';
    } else if (item.row != null) {
      var str = data.getFormattedValue(item.row, 0);
      message += '{row:' + item.row + ', column:none}; value (col 0) = ' + str + '\n';
    } else if (item.column != null) {
      var str = data.getFormattedValue(0, item.column);
      message += '{row:none, column:' + item.column + '}; value (row 0) = ' + str + '\n';
    }
  }
  if (message == '') {
    message = 'nothing';
  }
  alert('You selected ' + message);
}

तैयार है इवेंट

ज़्यादातर चार्ट एसिंक्रोनस रूप से रेंडर किए जाते हैं; जब आप draw() को कॉल करते हैं, तो उसके बाद सभी Google चार्ट तैयार इवेंट को दिखाते हैं. इससे पता चलता है कि चार्ट रेंडर हो गया है. इसके अलावा, चार्ट से प्रॉपर्टी लौटाने या दूसरे तरीकों से कॉल करने के लिए तैयार होता है. draw() पर कॉल करने के बाद इवेंट पर कॉल करने की कोशिश करने से पहले आपको हमेशा तैयार इवेंट को सुनना चाहिए.

आम तौर पर, "तैयार है" इवेंट को दिखाने वाले चार्ट, इन खास निर्देशों के मुताबिक बनाए जाते हैं:

  • तैयार इवेंट, हैंडलर को कोई भी प्रॉपर्टी पास नहीं करता है (आपके फ़ंक्शन हैंडलर को किसी भी पैरामीटर के पास होने की उम्मीद नहीं करनी चाहिए).
  • चार्ट, इंटरैक्शन के लिए तैयार होने के बाद तैयार इवेंट को शुरू करेगा. अगर चार्ट का आरेखण एसिंक्रोनस है, तो यह ज़रूरी है कि इंटरैक्शन के तरीकों को असल में कॉल किए जाने पर इवेंट सक्रिय किया जाए, न कि सिर्फ़ तब, जब draw तरीका खत्म हो जाए.
  • इस इवेंट में किसी लिसनर को जोड़ने के लिए, draw() तरीके को कॉल करने से पहले ऐसा करना ज़रूरी है. ऐसा नहीं करने पर, हो सकता है कि यह इवेंट, लिसनर के सेट अप हो जाने से पहले ही चालू हो जाए और आप उसे पकड़ न पाएं.
  • तैयार इवेंट के सक्रिय होने से पहले इंटरैक्शन के तरीकों को कॉल करने से, यह जोखिम है कि ये तरीके ठीक से काम नहीं करेंगे.

कन्वेंशन यह है कि "तैयार है" इवेंट सक्रिय न करने वाले चार्ट, draw तरीके के खत्म होने के तुरंत बाद इंटरैक्शन के लिए तैयार होते हैं और उपयोगकर्ता को कंट्रोल देते हैं. अगर आपका चार्ट किसी तैयार इवेंट को सक्रिय करता है, तो उसे कॉल करने से पहले, कॉल के हटने का इंतज़ार करना चाहिए, जैसा कि यहां दिखाया गया है:

google.visualization.events.addListener(tableChart, 'ready', myReadyHandler);

तैयार इवेंट हैंडलर सिंटैक्स

function myReadyHandler(){...}

तैयार इवेंट हैंडलर कोई पैरामीटर पास नहीं किया गया है.

गड़बड़ी इवेंट

अगर चार्ट में किसी तरह की गड़बड़ी आती है, तो आपको गड़बड़ी का इवेंट दिखाना चाहिए. इससे, इन गड़बड़ियों को अच्छी तरह से मैनेज किया जा सकता है. इवेंट हैंडलर को गड़बड़ी की जानकारी के साथ-साथ हर चार्ट के लिए खास कस्टम इवेंट प्रॉपर्टी भेजी जाती है. चार्ट में तुरंत बदलाव करने के तुरंत बाद, आपको इस इवेंट की सदस्यता लेनी चाहिए. इससे, आपको आने वाले समय में गड़बड़ी मिल सकती है.

आप goog.visualization.errors हेल्पर फ़ंक्शन का इस्तेमाल करके, उपयोगकर्ता को आसानी से गड़बड़ियां दिखा सकते हैं.

गड़बड़ी वाले इवेंट हैंडलर का सिंटैक्स

function myErrorHandler(err){...}

गड़बड़ी वाले इवेंट हैंडलर को इन सदस्यों वाला एक ऑब्जेक्ट पास करना ज़रूरी है:

  • id [ज़रूरी है] - चार्ट वाले DOM एलिमेंट का आईडी या अगर इसे रेंडर नहीं किया जा सकता, तो इसकी जगह गड़बड़ी का मैसेज दिखता है.
  • message [ज़रूरी है] - गड़बड़ी के बारे में बताने वाली छोटी मैसेज स्ट्रिंग.
  • detailedMessage [Optional] - गड़बड़ी के बारे में पूरी जानकारी.
  • विकल्प [ज़रूरी नहीं]- एक ऑब्जेक्ट, जिसमें इस गड़बड़ी और चार्ट के लिए सही कस्टम पैरामीटर हैं.

इवेंट मैनेज करने का उदाहरण

नीचे दिए गए उदाहरण में getSelection() और setSelection() दोनों को दिखाया गया है. यह डेटा की दो टेबल के बीच के सिंक को सिंक करता है. दूसरे चार्ट में चुने गए को सिंक करने के लिए, किसी भी चार्ट पर क्लिक करें.

// Create our two charts.
var table = new google.visualization.Table(document.getElementById('table_div'));
table.draw(data, {});

var orgchart = new google.visualization.OrgChart(document.getElementById('org_div'));
orgchart.draw(data, {});

// When the table is selected, update the orgchart.
google.visualization.events.addListener(table, 'select', function() {
  orgchart.setSelection(table.getSelection());
});

// When the orgchart is selected, update the table chart.
google.visualization.events.addListener(orgchart, 'select', function() {
  table.setSelection(orgchart.getSelection());
});

नीचे चुनी गई टेबल पर या चार्ट के एलिमेंट पर दिए गए चार्ट पर क्लिक करके, चुना गया विकल्प देखें: