مراسلة إطار iframe في Looker المُضمَّنة

1. قبل البدء

يجب أن يكون لديك محتوى Looker مضمّن داخل إطار iframe باستخدام التضمين الخاص أو التضمين عبر تسجيل الدخول الأحادي. في هذا الدرس التطبيقي حول الترميز، سنتفاعل مع إطار iframe من خلال JavaScript لجعل صفحة الويب أكثر ديناميكية. سترسل صفحة الويب رسائل إلى محتوى Looker المضمّن في الإطار المتضمّن (iframe) وستتلقّى رسائل منه.

المتطلبات الأساسية

أن يكون لديك نسخة Looker قيد التشغيل
لوحة بيانات Looker مضمَّنة بشكل خاص أو مضمَّنة باستخدام ميزة تسجيل الدخول الأحادي داخل إطار iframe
فهم طريقة window.postMessage()

ما ستتعلمه

كيفية إعداد إطار iframe ومثيل Looker للتفاعل مع JavaScript
كيفية الاستماع إلى الأحداث من إطار iframe
كيفية إرسال رسائل الإجراءات إلى إطار iframe

المتطلبات

الوصول إلى HTML وJavaScript الخاصين برمز الواجهة الأمامية الذي يدير إطار iframe
إذن الوصول إلى إعدادات التضمين الخاصة بالمشرف في مثيل Looker

2. التحضيرات

يجب إعداد إطار iframe ومثيل Looker قبل التفاعل مع إطار iframe.

إضافة سمة `id` إلى إطار iframe

عليك التحقّق من صحة الرسائل الواردة من إطار iframe. لإجراء ذلك، حدِّد السمة id على iframe:

<iframe 
    id="looker"
    src="https://instance_name.looker.com/embed/dashboards/1"
>
</iframe>

أضِف نطاق التضمين إلى `src` السمة الخاصة بإطار iframe

حدِّد نطاق صفحة الويب التي تستضيف إطار iframe. إذا كان عنوان URL لصفحة الويب هو https://mywebsite.com/with/embed، يكون نطاق صفحة الويب هو https://mywebsite.com.

إذا كنت تستخدم التضمين الخاص، أضِف النطاق كمعلَمة طلب بحث embed_domain في src الخاص بإطار iframe:

<iframe
    id="looker"
    src="https://instance_name.looker.com/embed/dashboards/1?embed_domain=https://mywebsite.com"
>
</iframe>

إذا كنت تستخدم تضمين الدخول المُوحَّد، أضِف النطاق كمَعلمة طلب بحث embed_domain إلى عنوان URL للتضمين.

إضافة نطاق التضمين إلى القائمة المسموح بها في مثيل Looker

أخيرًا، عليك إدراج نطاق التضمين في القائمة المسموح بها في مثيل Looker للسماح بإرسال الرسائل.

انتقِل إلى صفحة التضمين في قسم المشرف في مثيل Looker. https://your_instance.looker.com/admin/embed

في الحقل قائمة النطاقات المضمّنة المسموح بها، أدخِل نطاق التضمين. بعد كتابة النطاق، اضغط على مفتاح Tab ليظهر النطاق في مربّع. لا تُدرِج شرطة مائلة في النهاية /.

انقر على الزر تعديل.

3- الاستماع إلى رسائل الأحداث من الإطار iframe

يرسل إطار iframe الذي يتضمّن محتوى Looker رسائل إلى صفحة الويب المضيفة. تحتوي رسائل الأحداث هذه على معلومات في الوقت المناسب حول محتوى Looker المضمّن، مثل ما إذا كانت لوحة البيانات المضمّنة قد بدأت في التحميل أو إذا اختار المستخدم خيار "تنزيل" ضمن المحتوى المضمّن. لنستلم هذه الأحداث ونحلّلها.

فهم مخطط عنصر الحدث

مخطط عنصر الحدث هو:

{
  type: "...",
  eventSpecificProperty1: ...,
  eventSpecificProperty2: ...,
  ...
}

سيتضمّن الحدث دائمًا السمة type التي تتيح لك تحديد نوع الحدث. يتم تحديد جميع السمات الأخرى الخاصة بالحدث في مرجع الأحداث.

تلقّي الحدث وتحليله

أضِف هذا الرمز إلى المكان الذي يبدأ فيه JavaScript في صفحة الويب أو يدير إطار iframe:

window.addEventListener("message", function(message) {
  const iframeElement = document.getElementById("looker");
  if (message.source === iframeElement.contentWindow) {
    if (message.origin === "https://instance_name.looker.com") {
      const event = JSON.parse(message.data);
      switch (event.type):
        case "dashboard:run:start":
          console.log("The embedded dashboard has started loading"); 
    }
  }
});

ينفّذ مقتطف الرمز البرمجي ما يلي:

يستمع إلى الحدث "message" من العنصر window.
يتحقّق مما إذا كانت السمة source للرسالة هي iframe التي تتضمّن محتوى Looker المضمّن.
يتحقّق مما إذا كانت السمة origin للرسالة هي نطاق مثيل Looker.
يحلّل JSON السمة data للرسالة من أجل الوصول إلى عنصر الحدث وتحليله.
يتم استخدام مفاتيح التبديل في السمة type الخاصة بعنصر الحدث لتحديد نوع الحدث واتّخاذ إجراء بشأنه.

يمكن الآن لصفحة الويب المضيفة التفاعل ديناميكيًا مع الأحداث التي يصدرها محتوى Looker المضمّن.

4. إرسال رسالة إجراء إلى الإطار المتضمّن (iframe)

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

إنشاء رسالة إجراء

أنشئ رسالة إجراء داخل JavaScript الخاص بصفحة الويب:

const action = { type: "dashboard:run" };
const actionJSONFormatted = JSON.stringify(action);

يتّبع العنصر action التنسيق نفسه الخاص بالعنصر event السابق. سيتضمّن دائمًا السمة type، بالإضافة إلى سمات خاصة بالإجراء محدّدة في مرجع الإجراءات. يجب أن تكون رسالة الإجراء بتنسيق JSON.

إرسال رسالة الإجراء

داخل JavaScript الخاص بصفحة الويب، أرسِل الإجراء المنسَّق بتنسيق JSON إلى إطار iframe:

const iframeElement = document.getElementById("looker");
iframeElement.contentWindow.postMessage(actionJSONFormatted, 'https://instance_name.looker.com');

حدِّد إطار iframe الذي سترسل إليه الإجراء.
استدعِ الطريقة postMessage() في السمة contentWindow الخاصة بإطار iframe لإرسال الرسالة.

يمكن لصفحة الويب المضيفة الآن تغيير حالة محتوى Looker المضمّن بشكل ديناميكي.

5- معلومات إضافية

تهانينا! يمكنك الآن الاستماع إلى الأحداث من محتوى Looker المضمّن في إطار iframe وإرسال الإجراءات إليه. يمكنك الاطّلاع على المراجع التالية للحصول على مزيد من المعلومات:

مرجع الأحداث لجميع الأحداث المتاحة وخصائصها
مرجع الإجراءات لجميع الإجراءات المتاحة وخصائصها
أفضل ممارسات الأمان المتعلّقة بتضمين محتوى Looker