টেক্সট ইনপুট জন্য স্বয়ংসম্পূর্ণ পরামর্শ

টেক্সট ইনপুট উইজেট আপনার অ্যাড-অনকে ব্যবহারকারীদের প্রদত্ত টেক্সট পড়তে এবং প্রতিক্রিয়া জানাতে দেয়। আপনি এই উইজেটগুলিকে ব্যবহারকারীদের ইনপুট টেক্সটের জন্য স্বয়ংক্রিয় পরামর্শ প্রদানের জন্য কনফিগার করতে পারেন।

প্রদত্ত পরামর্শগুলি আপনার প্রদত্ত স্ট্রিংগুলির একটি স্ট্যাটিক তালিকা থেকে আসতে পারে। বিকল্পভাবে, আপনি প্রসঙ্গ থেকে পরামর্শগুলি তৈরি করতে পারেন, যেমন ব্যবহারকারী ইতিমধ্যেই উইজেটে টাইপ করা টেক্সট।

পরামর্শ কনফিগার করা হচ্ছে

টেক্সট ইনপুটের জন্য পরামর্শ কনফিগার করার জন্য আপনাকে কেবল নিম্নলিখিতগুলি করতে হবে:

• পরামর্শের একটি তালিকা তৈরি করুন:
  • একটি স্থির তালিকা তৈরি করা, এবং/অথবা
  • একটি কলব্যাক ফাংশনের সাহায্যে একটি অ্যাকশন সংজ্ঞায়িত করা যা প্রসঙ্গ থেকে গতিশীলভাবে সেই তালিকা তৈরি করে।
• টেক্সট ইনপুট উইজেটে পরামর্শ তালিকা এবং/অথবা ক্রিয়া সংযুক্ত করুন।

যদি আপনি একটি স্থির তালিকার পরামর্শ এবং একটি ক্রিয়া উভয়ই প্রদান করেন, তাহলে অ্যাপ্লিকেশন UI স্থির তালিকা ব্যবহার করে যতক্ষণ না ব্যবহারকারী অক্ষর প্রবেশ করা শুরু করে, যার ফলে কলব্যাক ফাংশন ব্যবহার করা হয় এবং স্থির তালিকা উপেক্ষা করা হয়।

স্থির পরামর্শ

পরামর্শের একটি স্থির তালিকা প্রদান করতে, আপনাকে কেবল নিম্নলিখিতগুলি করতে হবে:

1. একটি Suggestions অবজেক্ট তৈরি করুন।
2. addSuggestion() অথবা addSuggestions() ব্যবহার করে প্রতিটি স্ট্যাটিক সাজেশন এতে যোগ করুন।
3. TextInput.setSuggestions() ব্যবহার করে উইজেটে Suggestions অবজেক্টটি সংযুক্ত করুন।

UI স্ট্যাটিক সাজেশনগুলিকে যে ক্রমে যোগ করা হয়েছিল সেই ক্রমে প্রদর্শন করে। UI স্বয়ংক্রিয়ভাবে কেস-অসংবেদনশীল প্রিফিক্স ম্যাচিং সম্পাদন করে এবং ব্যবহারকারী উইজেটে অক্ষর টাইপ করার সাথে সাথে সাজেশন তালিকাটি ফিল্টার করে।

পরামর্শমূলক ক্রিয়া

যদি আপনি একটি স্ট্যাটিক সাজেশন লিস্ট ব্যবহার না করেন, তাহলে আপনার সাজেশনগুলিকে গতিশীলভাবে তৈরি করার জন্য আপনাকে একটি অ্যাকশন নির্ধারণ করতে হবে। আপনি এই পদক্ষেপগুলি অনুসরণ করে এটি করতে পারেন:

1. একটি Action অবজেক্ট তৈরি করুন এবং এটি আপনার সংজ্ঞায়িত একটি কলব্যাক ফাংশনের সাথে সংযুক্ত করুন।
2. উইজেটের TextInput.setSuggestionsAction() ফাংশনটি কল করুন, এটিতে Action অবজেক্টটি প্রদান করুন।
3. সাজেশন তালিকা তৈরি করতে এবং একটি বিল্ট SuggestionsResponse অবজেক্ট ফেরত দিতে কলব্যাক ফাংশনটি প্রয়োগ করুন।

ব্যবহারকারী যখনই টেক্সট ইনপুটে কোনও অক্ষর টাইপ করেন, তখনই UI কলব্যাক ফাংশনটি কল করে, কিন্তু ব্যবহারকারী কিছুক্ষণের জন্য টাইপ করা বন্ধ করার পরেই। কলব্যাক ফাংশনটি একটি ইভেন্ট অবজেক্ট পায় যাতে ওপেন কার্ডের উইজেট সম্পর্কে তথ্য থাকে। বিস্তারিত জানার জন্য অ্যাকশন ইভেন্ট অবজেক্ট দেখুন।

কলব্যাক ফাংশনটি অবশ্যই একটি বৈধ SuggestionsResponse অবজেক্ট ফেরত পাঠাবে যাতে প্রদর্শনের জন্য পরামর্শের তালিকা থাকবে। UI পরামর্শগুলিকে সেই ক্রমে প্রদর্শন করবে যেভাবে সেগুলি যোগ করা হয়েছে। স্ট্যাটিক তালিকার বিপরীতে, UI ব্যবহারকারীর ইনপুটের উপর ভিত্তি করে কলব্যাক পরামর্শগুলির কোনও স্বয়ংক্রিয় ফিল্টারিং পরিচালনা করে না। আপনি যদি এই ধরণের ফিল্টারিং পেতে চান, তাহলে আপনাকে ইভেন্ট অবজেক্ট থেকে টেক্সট ইনপুট মানটি পড়তে হবে এবং তালিকা তৈরি করার সময় আপনার পরামর্শগুলি ফিল্টার করতে হবে।

উদাহরণ

নিম্নলিখিত Google Workspace অ্যাড-অন কোড স্নিপেটটি দেখায় কিভাবে দুটি ভিন্ন টেক্সট ইনপুট উইজেটে পরামর্শ কনফিগার করতে হয়, প্রথমটি একটি স্ট্যাটিক তালিকা সহ এবং দ্বিতীয়টি একটি কলব্যাক ফাংশন ব্যবহার করে:

// Create an input with a static suggestion list.
var textInput1 = CardService.newTextInput()
    .setFieldName('colorInput')
    .setTitle('Color choice')
    .setSuggestions(CardService.newSuggestions()
        .addSuggestion('Red')
        .addSuggestion('Yellow')
        .addSuggestions(['Blue', 'Black', 'Green']));

// Create an input with a dynamic suggestion list.
var action = CardService.newAction()
    .setFunctionName('refreshSuggestions');
var textInput2 = CardService.newTextInput()
    .setFieldName('emailInput')
    .setTitle('Email')
    .setSuggestionsAction(action);

// ...

/**
 *  Build and return a suggestion response. In this case, the suggestions
 *  are a list of emails taken from the To: and CC: lists of the open
 *  message in Gmail, filtered by the text that the user has already
 *  entered. This method assumes the Google Workspace
 *  add-on extends Gmail; the add-on only calls this method for cards
 *  displayed when the user has entered a message context.
 *
 *  @param {Object} e the event object containing data associated with
 *      this text input widget.
 *  @return {SuggestionsResponse}
 */
 function refreshSuggestions(e) {
   // Activate temporary Gmail scopes, in this case so that the
   // open message metadata can be read.
   var accessToken = e.gmail.accessToken;
   GmailApp.setCurrentMessageAccessToken(accessToken);

   var userInput = e && e.formInput['emailInput'].toLowerCase();
   var messageId = e.gmail.messageId;
   var message = GmailApp.getMessageById(messageId);

   // Combine the comma-separated returned by these methods.
   var addresses = message.getTo() + ',' + message.getCc();

   // Filter the address list to those containing the text the user
   // has already entered.
   var suggestionList = [];
   addresses.split(',').forEach(function(email) {
     if (email.toLowerCase().indexOf(userInput) !== -1) {
       suggestionList.push(email);
     }
   });
   suggestionList.sort();

   return CardService.newSuggestionsResponseBuilder()
       .setSuggestions(CardService.newSuggestions()
           .addSuggestions(suggestionList))
       .build();  // Don't forget to build the response!
 }

পরামর্শ এবং OnChangeAction()

টেক্সট ইনপুট উইজেটগুলিতে একটি setOnChangeAction() হ্যান্ডলার ফাংশন সংজ্ঞায়িত থাকতে পারে যা উইজেট ফোকাস হারানোর সাথে সাথে কার্যকর হয়। যদি এই হ্যান্ডলার এবং সাজেশন উভয়ই একই টেক্সট ইনপুটের জন্য সক্ষম করা থাকে, তাহলে নিম্নলিখিত নিয়মগুলি টেক্সট ইনপুট ইন্টারঅ্যাকশন আচরণকে সংজ্ঞায়িত করে:

1. একটি সাজেশন নির্বাচন করার পর setOnChangeAction() হ্যান্ডলারটি কার্যকর হয়।
2. যদি ব্যবহারকারী নির্বাচিত পরামর্শ পরিবর্তন না করেই Enter চাপেন (অথবা অন্যথায় টেক্সট ইনপুট ফোকাস হারান), তাহলে setOnChangeAction() আবার ট্রিগার হয় না।
3. যদি ব্যবহারকারী কোনও পরামর্শ নির্বাচন করার পরে এটি এমনভাবে সম্পাদনা করে যে এটি তালিকার কোনও পরামর্শের সাথে আর মেলে না, তাহলে setOnChangeAction() আবার ট্রিগার করে।
4. যদি ব্যবহারকারী কোনও পরামর্শ নির্বাচন না করেন, তাহলে টেক্সট ইনপুট ফোকাস হারিয়ে ফেললে setOnChangeAction() ট্রিগার হয়।