এডিটর অ্যাড-অনগুলির জন্য ট্রিগার, এডিটর অ্যাড-অনগুলির জন্য ট্রিগার, সম্পাদক অ্যাড-অনগুলির জন্য ট্রিগার

অ্যাপস স্ক্রিপ্ট ট্রিগার একটি নির্দিষ্ট ইভেন্ট ঘটলে একটি নির্দিষ্ট স্ক্রিপ্ট ফাংশন ( ট্রিগার ফাংশন ) কার্যকর করে। শুধুমাত্র নির্দিষ্ট কিছু ইভেন্টই ট্রিগার সক্রিয় করতে পারে এবং প্রতিটি গুগল ওয়ার্কস্পেস অ্যাপ্লিকেশন ভিন্ন ভিন্ন ইভেন্ট সেট সমর্থন করে।

যখন কোনো ট্রিগার সক্রিয় হয়, তখন একটি ইভেন্ট অবজেক্ট তৈরি হয়। এই JSON কাঠামোটিতে সংঘটিত ঘটনাটির বিস্তারিত বিবরণ থাকে। ট্রিগারের প্রকারভেদের উপর ভিত্তি করে ইভেন্ট অবজেক্ট কাঠামোর তথ্যগুলো ভিন্নভাবে সাজানো থাকে।

ইভেন্ট অবজেক্টটি তৈরি হয়ে গেলে, অ্যাপস স্ক্রিপ্ট এটিকে ট্রিগার ফাংশনে একটি প্যারামিটার হিসেবে পাঠায়। ট্রিগার ফাংশন হলো একটি কলব্যাক ফাংশন যা আপনাকে অবশ্যই নিজে থেকে ইমপ্লিমেন্ট করতে হবে, যাতে ইভেন্টের প্রতিক্রিয়ায় উপযুক্ত পদক্ষেপগুলো নেওয়া যায়। উদাহরণস্বরূপ, একটি এডিটর অ্যাড-অনে, ডকুমেন্ট খোলার সময় অ্যাড-অন মেনু আইটেম তৈরি করার জন্য একটি ট্রিগার ব্যবহার করা হয়। এই ক্ষেত্রে, অ্যাড-অনের প্রয়োজনীয় মেনু আইটেমগুলো তৈরি করার জন্য আপনি একটি onOpen(e) ট্রিগার ফাংশন ইমপ্লিমেন্ট করবেন, যেখানে সম্ভবত ইভেন্ট অবজেক্টের ডেটা ব্যবহার করা হবে।

এই পৃষ্ঠায় এডিটর অ্যাড-অন প্রজেক্টে ট্রিগার ব্যবহারের নির্দেশিকা দেওয়া হয়েছে।

এডিটর অ্যাড-অন ট্রিগারের প্রকারভেদ

আপনি এডিটর অ্যাড-অনগুলিতে গুগল অ্যাপস স্ক্রিপ্ট প্রোজেক্টের জন্য উপলব্ধ বেশিরভাগ জেনেরিক ট্রিগার টাইপ ব্যবহার করতে পারেন, যার মধ্যে সিম্পল ট্রিগার এবং বেশিরভাগ ইনস্টলেবল ট্রিগার অন্তর্ভুক্ত। উপলব্ধ ট্রিগার টাইপগুলির সঠিক সেট নির্ভর করে যে অ্যাপ্লিকেশনটিকে এক্সটেন্ড করা হচ্ছে তার উপর।

এডিটর অ্যাড-অনগুলির মতো নয়, গুগল ওয়ার্কস্পেস অ্যাড-অনগুলি সাধারণ অ্যাপস স্ক্রিপ্ট সিম্পল বা ইনস্টলেবল ট্রিগার ব্যবহার করতে পারে না। পরিবর্তে, এগুলি গুগল ওয়ার্কস্পেস অ্যাড-অনগুলির জন্য বিশেষভাবে ডিজাইন করা ট্রিগার ব্যবহার করে। আরও তথ্যের জন্য, গুগল ওয়ার্কস্পেস অ্যাড-অন ট্রিগার দেখুন।

নিম্নলিখিত সারণিতে এডিটর অ্যাড-অনগুলি যে ধরনের সহজ এবং ইনস্টলযোগ্য ট্রিগার ব্যবহার করতে পারে তা দেখানো হয়েছে এবং সংশ্লিষ্ট ইভেন্ট অবজেক্টগুলির লিঙ্ক দেওয়া হয়েছে:

অনুষ্ঠান	ইভেন্ট অবজেক্ট	সাধারণ ট্রিগার	ইনস্টলযোগ্য ট্রিগার
খোলা একটি এডিটর ফাইল খোলা হয়েছে।	ডক্স অনওপেন ইভেন্ট অবজেক্ট ফর্মের onOpen ইভেন্ট অবজেক্ট শীট onOpen ইভেন্ট অবজেক্ট onOpen ইভেন্ট অবজেক্ট স্লাইড করে	ডাক্তাররা ফর্ম* শীট স্লাইড function onOpen(e)	ডাক্তাররা ফর্ম শীট
ইনস্টল করুন অ্যাড-অনটি ইনস্টল করা হয়েছে।	onInstall ইভেন্ট অবজেক্ট	ডাক্তাররা ফর্ম শীট স্লাইড function onInstall(e)
সম্পাদনা স্প্রেডশিট সেলের বিষয়বস্তু পরিবর্তন করা হয়েছে।	শীট onEdit ইভেন্ট অবজেক্ট	শীট function onEdit(e)	শীট
পরিবর্তন একটি শীটের বিষয়বস্তু সম্পাদনা বা বিন্যাস করা হয়।	শীটগুলির onChange ইভেন্ট অবজেক্ট		শীট
ফর্ম জমা দিন একটি গুগল ফর্ম জমা দেওয়া হয়েছে।	ফর্ম-সাবমিট ইভেন্ট অবজেক্ট শীট ফর্ম-সাবমিট ইভেন্ট অবজেক্ট		ফর্ম শীট
সময়-চালিত (ঘড়ি) ট্রিগারটি একটি নির্দিষ্ট সময়ে বা বিরতিতে সক্রিয় হয়।	সময়-চালিত ইভেন্ট অবজেক্ট	ডাক্তাররা ফর্ম শীট স্লাইড

গুগল ফর্মের ওপেন ইভেন্টটি তখন ঘটে না যখন কোনো ব্যবহারকারী উত্তর দেওয়ার জন্য ফর্মটি খোলে, বরং তখন ঘটে যখন কোনো সম্পাদক ফর্মটি পরিবর্তন করার জন্য খোলে।

অ্যাড-অনগুলিতে সহজ ট্রিগার

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

নিম্নলিখিত সংরক্ষিত নামগুলির মধ্যে একটি ব্যবহার করে একটি ফাংশন প্রয়োগ করার মাধ্যমে আপনি একটি অ্যাড-অনে একটি সাধারণ ট্রিগার যোগ করতে পারেন:

• যখন কোনো ব্যবহারকারী একটি ডকুমেন্ট, স্প্রেডশীট বা প্রেজেন্টেশন খোলে, তখন onOpen কার্যকর হয়। এডিটরে কোনো ফর্ম খোলার সময়েও onOpen কার্যকর হতে পারে (কিন্তু ফর্মে উত্তর দেওয়ার সময়ে নয়)। এটি কেবল তখনই কার্যকর হয় যখন ব্যবহারকারীর সংশ্লিষ্ট ফাইলটি সম্পাদনা করার অনুমতি থাকে এবং এটি বেশিরভাগ ক্ষেত্রে মেনু আইটেম তৈরি করতে ব্যবহৃত হয়।
• যখন কোনো ব্যবহারকারী একটি অ্যাড-অন ইনস্টল করেন, তখন onInstall কার্যকর হয়। সাধারণত onInstall শুধু onOpen কল করার জন্যই ব্যবহৃত হয়; এটি নিশ্চিত করে যে ব্যবহারকারীকে পৃষ্ঠাটি রিফ্রেশ করার প্রয়োজন ছাড়াই ইনস্টলের পরপরই অ্যাড-অন মেনুগুলো প্রদর্শিত হয়।
• যখন কোনো ব্যবহারকারী স্প্রেডশীটে কোনো সেলের মান পরিবর্তন করেন, তখন onEdit কার্যকর হয়। সেল সরানো, ফরম্যাটিং বা এমন কোনো পরিবর্তনের ফলে এই ট্রিগারটি সক্রিয় হয় না, যেগুলোতে সেলের মানের কোনো পরিবর্তন হয় না।

বিধিনিষেধ

অ্যাড-অনের সিম্পল ট্রিগারগুলো সেই একই বিধিনিষেধের অধীন, যা অন্যান্য ধরনের অ্যাপস স্ক্রিপ্ট প্রোজেক্টের সিম্পল ট্রিগারগুলোর ক্ষেত্রে প্রযোজ্য। অ্যাড-অন ডিজাইন করার সময় এই বিধিনিষেধগুলো বিশেষভাবে লক্ষ্য করুন:

• কোনো ফাইল রিড-অনলি (ভিউ বা কমেন্ট) মোডে খোলা থাকলে সিম্পল ট্রিগারগুলো চলে না। এই আচরণের কারণে আপনার অ্যাড-অন মেনুগুলো ডেটা দিয়ে পূর্ণ হতে পারে না।
• কিছু নির্দিষ্ট পরিস্থিতিতে, এডিটর অ্যাড-অনগুলো তাদের onOpen এবং onEdit সিম্পল ট্রিগারগুলো কোনো অনুমোদন ছাড়াই মোডে চালায়। অ্যাড-অন অনুমোদন মডেলে বর্ণিত জটিলতাগুলো এই মোডের কারণে সৃষ্টি হয়।
• অ্যাড-অন অনুমোদন মডেলে বর্ণিত ক্ষেত্রগুলো ছাড়া, সাধারণ ট্রিগারগুলো কোনো পরিষেবা ব্যবহার করতে বা অনুমোদনের প্রয়োজন হয় এমন অন্য কোনো কাজ করতে পারে না।
• সিম্পল ট্রিগার ৩০ সেকেন্ডের বেশি চলতে পারে না। একটি সিম্পল ট্রিগার ফাংশনে প্রসেসিংয়ের পরিমাণ ন্যূনতম রাখুন।
• সাধারণ ট্রিগারগুলো অ্যাপস স্ক্রিপ্ট ট্রিগার কোটার সীমার অধীন।

অ্যাড-অনগুলিতে ইনস্টলযোগ্য ট্রিগার

অ্যাড-অনগুলি অ্যাপস Script সার্ভিস ব্যবহার করে প্রোগ্রাম্যাটিকভাবে ইনস্টলযোগ্য ট্রিগার তৈরি এবং পরিবর্তন করতে পারে। অ্যাড-অন ইনস্টলযোগ্য ট্রিগার ম্যানুয়ালি তৈরি করা যায় না। সাধারণ ট্রিগারের বিপরীতে, ইনস্টলযোগ্য ট্রিগারগুলি এমন পরিষেবা ব্যবহার করতে পারে যার জন্য অনুমোদনের প্রয়োজন হয়।

অ্যাড-অনের ইনস্টলযোগ্য ট্রিগারগুলো কোনো ত্রুটির সম্মুখীন হলে ব্যবহারকারীকে ত্রুটির ইমেল পাঠায় না, কারণ বেশিরভাগ ক্ষেত্রেই ব্যবহারকারী নিজে থেকে সমস্যাটির সমাধান করতে পারেন না। এই কারণে, যখনই সম্ভব, আপনার অ্যাড-অনটিকে এমনভাবে ডিজাইন করা উচিত যাতে এটি ব্যবহারকারীর পক্ষ থেকে সুন্দরভাবে ত্রুটিগুলো সামাল দিতে পারে।

অ্যাড-অনগুলি নিম্নলিখিত ইনস্টলযোগ্য ট্রিগারগুলি ব্যবহার করতে পারে:

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

• গুগল ফর্মের কোনো উত্তর জমা দেওয়া হলে ফর্ম-সাবমিট ইনস্টলেবল ট্রিগারগুলো কার্যকর হয়।

  ফর্ম-সাবমিট ট্রিগারের দুটি সংস্করণ রয়েছে: একটি শীটস-এর জন্য (যেখানে ফর্মের উত্তরগুলো সংগ্রহ করা হয়) এবং অন্যটি গুগল ফর্মস-এর জন্য। শীটস ফর্ম-সাবমিট ট্রিগার ফাংশনে পাস করা ইভেন্ট অবজেক্টটি সরল এবং এটি সাধারণ অ্যারেতে উত্তরের মানগুলো ফেরত দেয়। ফর্মস ফর্ম-সাবমিট ট্রিগার ফাংশনে পাস করা ইভেন্ট অবজেক্টটি একটি FormResponse অবজেক্টের মধ্যে আরও বেশি তথ্য প্রদান করে।

• টাইম-ড্রাইভেন ট্রিগার (যাকে ক্লক ট্রিগারও বলা হয়) একটি নির্দিষ্ট সময়ে অথবা নিয়মিত সময় ব্যবধানে বারবার সক্রিয় হয়।

ইনস্টলযোগ্য ট্রিগার অনুমোদন করুন

সাধারণত, যদি কোনো ডেভেলপার অতিরিক্ত অনুমোদনের প্রয়োজন এমন নতুন পরিষেবা ব্যবহার করার জন্য কোনো অ্যাড-অন আপডেট করেন, তাহলে ব্যবহারকারীদের পরবর্তীবার এটি ব্যবহার করার সময় অ্যাড-অনটি পুনরায় অনুমোদন করার জন্য অনুরোধ করা হয়।

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

সাধারণ অ্যাপস স্ক্রিপ্ট প্রোজেক্টের ট্রিগারের মতো নয়, অ্যাড-অনের ট্রিগারগুলো পুনরায় অনুমোদনের প্রয়োজন হলেও ফায়ার হতে থাকে। তবে, স্ক্রিপ্টটি যদি এমন কোনো কোড লাইনে পৌঁছায় যার জন্য প্রয়োজনীয় অনুমোদন তার কাছে নেই, তাহলে সেটি ব্যর্থ হয়। এটি এড়ানোর জন্য, অ্যাড-অনের বিভিন্ন ভার্সনের মধ্যে পরিবর্তিত হওয়া কোডের অংশগুলোতে অ্যাক্সেস সীমিত করতে ScriptApp.getAuthorizationInfo ব্যবহার করুন।

নিম্নলিখিত উদাহরণগুলি ট্রিগার ফাংশনে ব্যবহারের জন্য প্রস্তাবিত কাঠামো দেখায়, যা অনুমোদন সংক্রান্ত সমস্যা এড়াতে সাহায্য করে। উদাহরণস্বরূপ ট্রিগার ফাংশনটি একটি গুগল শিটস অ্যাড-অনের মধ্যে একটি ফর্ম-সাবমিট ইভেন্টে সাড়া দেয় এবং, যদি পুনরায় অনুমোদনের প্রয়োজন হয়, তবে টেমপ্লেটেড HTML ব্যবহার করে অ্যাড-অনটির ব্যবহারকারীকে একটি অ্যালার্ট ইমেল পাঠায়।

/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = "My Add-on Title";
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (
    authInfo.getAuthorizationStatus() === ScriptApp.AuthorizationStatus.REQUIRED
  ) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty("lastAuthEmailDate");
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile("AuthorizationEmail");
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(
          Session.getEffectiveUser().getEmail(),
          "Authorization Required",
          message.getContent(),
          {
            name: addonTitle,
            htmlBody: message.getContent(),
          },
        );
      }
      props.setProperty("lastAuthEmailDate", today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

বিধিনিষেধ

অ্যাড-অনগুলিতে ইনস্টলযোগ্য ট্রিগারগুলি সেই একই বিধিনিষেধের অধীন, যা অন্যান্য ধরণের অ্যাপস স্ক্রিপ্ট প্রোজেক্টে ইনস্টলযোগ্য ট্রিগারগুলির ক্ষেত্রে প্রযোজ্য।

এই বিধিনিষেধগুলো ছাড়াও, বিশেষত অ্যাড-অনগুলিতে ইনস্টলযোগ্য ট্রিগারগুলির ক্ষেত্রে বেশ কিছু বিধিনিষেধ প্রযোজ্য:

• প্রতিটি অ্যাড-অনে, প্রতি ব্যবহারকারী এবং প্রতি ডকুমেন্টের জন্য, প্রতিটি ধরণের কেবল একটি ট্রিগার থাকতে পারে। উদাহরণস্বরূপ, একটি নির্দিষ্ট স্প্রেডশীটে, একজন নির্দিষ্ট ব্যবহারকারীর কেবল একটি এডিট ট্রিগার থাকতে পারে, যদিও সেই ব্যবহারকারীর একই স্প্রেডশীটে একটি ফর্ম-সাবমিট ট্রিগার বা একটি টাইম-ড্রাইভেন ট্রিগারও থাকতে পারে। একই স্প্রেডশীটে অ্যাক্সেস থাকা অন্য কোনো ব্যবহারকারীর নিজস্ব আলাদা ট্রিগারের সেট থাকতে পারে।
• অ্যাড-অন শুধুমাত্র সেই ফাইলের জন্যই ট্রিগার তৈরি করতে পারে, যে ফাইলে অ্যাড-অনটি ব্যবহৃত হয়। অর্থাৎ, গুগল ডক ‘এ’-তে ব্যবহৃত একটি অ্যাড-অন, গুগল ডক ‘বি’ কখন খোলা হচ্ছে তা নিরীক্ষণের জন্য কোনো ট্রিগার তৈরি করতে পারে না।
• সময়-চালিত ট্রিগারগুলো প্রতি ঘণ্টায় একবারের বেশি চলতে পারে না।
• যখন কোনো ইনস্টলেবল ট্রিগার দ্বারা চালিত কোড কোনো এক্সেপশন থ্রো করে, তখন অ্যাড-অনগুলো স্বয়ংক্রিয়ভাবে ব্যবহারকারীকে ইমেল পাঠায় না। ব্যর্থতার ঘটনাগুলো পরীক্ষা করা এবং সেগুলোকে সুষ্ঠুভাবে সামাল দেওয়ার দায়িত্ব ডেভেলপারের।
• নিম্নলিখিত পরিস্থিতিগুলির যেকোনো একটিতে অ্যাড-অন ট্রিগারগুলি কাজ করা বন্ধ করে দেয়:
  • যদি ব্যবহারকারী অ্যাড-অনটি আনইনস্টল করে দেন,
  • যদি কোনো ডকুমেন্টে অ্যাড-অনটি নিষ্ক্রিয় করা হয় (যদি এটি পুনরায় সক্রিয় করা হয়, ট্রিগারটি আবার কার্যকর হয়ে যায়), অথবা
  • যদি ডেভেলপার অ্যাড-অনটি অপ্রকাশিত করে দেয় অথবা অ্যাড-অন স্টোরে একটি ত্রুটিপূর্ণ সংস্করণ জমা দেয়।
• অ্যাড-অন ট্রিগার ফাংশনগুলো ততক্ষণ পর্যন্ত চলতে থাকে যতক্ষণ না তারা এমন কোনো কোডে পৌঁছায় যেখানে একটি অননুমোদিত পরিষেবা ব্যবহৃত হয়, এবং সেই মুহূর্তে সেগুলো থেমে যায়। এটি শুধুমাত্র তখনই সত্য যখন অ্যাড-অনটি প্রকাশিত হয়; একটি সাধারণ অ্যাপস স্ক্রিপ্ট প্রজেক্ট বা একটি অপ্রকাশিত অ্যাড-অনের ক্ষেত্রে একই ট্রিগার মোটেও চলে না, যদি স্ক্রিপ্টের কোনো অংশের জন্য অনুমোদনের প্রয়োজন হয়।
• ইনস্টলযোগ্য ট্রিগারগুলো অ্যাপস স্ক্রিপ্ট ট্রিগার কোটার সীমার অধীন।