البرامج المساعدة

نظرة عامة

يتيح LimeSurvey إمكانية إضافة وظائف جديدة عبر البرامج المساعدة. يأتي LimeSurvey بالفعل مزوداً بعدد جيد من البرامج المساعدة الأساسية. كما يمكنك الاطلاع على قائمة البرامج المساعدة من جهات خارجية، وربما تضيف في المستقبل برنامجك المساعد الخاص إليها!

تتيح البرامج المساعدة للمستخدمين تخصيص وظائف نسختهم المثبّتة مع الاستمرار في الاستفادة من تحديثات البرنامج المنتظمة.

هذا الدليل موجّه للمطورين الذين يوسّعون LimeSurvey لاستخدامهم الخاص أو لعملائهم؛ ولن يفيد المستخدمين النهائيين.

يجب أن تنفّذ البرامج المساعدة الواجهة iPlugin. نوصي بأن يرث صنف البرنامج المساعد الخاص بك من الصنف PluginBase.

تُطوَّر البرامج المساعدة اعتماداً على آلية الأحداث.

إعدادات البرنامج المساعد

عند الوراثة تستفيد من الوظائف المشتركة التي تحتاجها البرامج المساعدة والتي نفّذناها لك مسبقاً. ومن هذه الوظائف تنفيذ الدالة getPluginSettings. يجب أن تعيد هذه الدالة صفيفاً يصف خيارات الضبط المتاحة للمستخدم.

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

protected $settings = array(
    'logo' => array(
          'type' => 'logo',
          'path' => 'assets/logo.png'
     ),

     'message' => array(
          'type' => 'string',
          'label' => 'Message'
     )
);

يحتوي الصفيف على اسم لكل إعداد كمفتاح. أما القيم فهي صفائف تحتوي على البيانات الوصفية المطلوبة.

الأنواع المدعومة هي:

• logo
• int (عدد صحيح)
• string (أبجدي رقمي)
• text
• html
• relevance
• info
• password
• date
• select

إضافة إلى النوع (type)، تتوفر عدة مفاتيح أخرى:

• label: يحدد العلامة
• default: يحدد القيمة التي تُعرض إذا لم تُحدد أي قيمة (للإعدادات العامة فقط، وليس لإعدادات الاستبيان)
• current: يحدد القيمة الحالية.
• readOnly : يعرض الإعدادات للقراءة فقط
• htmlOptions: خيارات htmlOptions لجزء الإدخال ( راجع دليل Yii [[١]])
• pluginOptions: لبعض الإعدادات (html أو select) : لضبط خيار عنصر الواجهة (widget)
• labelOptions : خيارات htmlOptions للعلامة
• controlOptions : خيارات htmlOptions للعنصر الذي يحيط بالعلامة وحقل الإدخال
• localized : إذا كانت القيمة true، تُخزَّن القيمة لكل لغة. يُرسَل الإدخال على الصيغة name[language] ويجب أن تكون current صفيفاً مفهرساً برمز اللغة.
• language : يُستخدم مع localized. إما رمز لغة واحد، أو ^{(New in X.Y.Z )} صفيف من رموز اللغات لعرض حقل إدخال واحد لكل لغة (راجع إعدادات البرنامج المساعد المترجمة)

يمكنك العثور على مثال لبرنامج مساعد يستخدم جميع الإعدادات الحالية في exampleSettings

قراءة إعدادات البرنامج المساعد وكتابتها

يمكنك قراءة إعدادات البرنامج المساعد وكتابتها مباشرة من الشيفرة البرمجية للبرنامج المساعد.

مثال:

$mySetting = $this->get('mySetting');
$this->set('mySetting', $mySetting + 1);

يمكنك الحصول على القيمة الافتراضية إذا كان الإعداد فارغاً (null):

$mySetting = $this->get('mySetting', null, null, 10);  // 10 هي القيمة الافتراضية

إعدادات البرنامج المساعد الخاصة باستبيان معيّن

يُستخدم حدثان لإنشاء إعدادات البرنامج المساعد الخاصة باستبيان معيّن:

• newSurveySettings
• beforeSurveySettings

مثال على تعطيل برنامج مساعد لاستبيان معيّن:

    public function init()
    {
        $this->subscribe('beforeSurveySettings');
        $this->subscribe('newSurveySettings');
        // Other events...
    }

    public function beforeSurveySettings()
    {
	    $event = $this->event;
	    $surveyId = intval($event->get('survey'));

        $event->set(
            "surveysettings.{$this->id}",
            [
                'name' => get_class($this),
                'settings' => [
                    'isActive' => [
                        'type' => 'boolean',
                        'label' => 'isActive',
                        'current' => $this->getIsActive($surveyId),
                        'help' => 'Activate plugin for this survey'
                    ],
                ]
            ]
        );
    }

    public function newSurveySettings()
    {
        $event = $this->event;
        foreach ($event->get('settings') as $name => $value)
        {
            $this->set($name, $value, 'Survey', $event->get('survey'), false);
        }
    }

    private function getIsActive(int $sid): bool
    {
        return (bool) $this->get('isActive', 'Survey', $sid, false);
    }

<span id="Localized_plugin_settings_ ^{(New in 7.4 )}">

إعدادات البرنامج المساعد المترجمة ^{(New in 7.4 )}

لعرض حقل إدخال واحد لكل لغة من لغات الاستبيان لنفس الإعداد، اضبط localized على true ومرّر قائمة اللغات في language. يتم إلحاق اسم اللغة بعلامة كل حقل إدخال.

    public function beforeSurveySettings()
    {
        $event = $this->event;
        $surveyId = intval($event->get('survey'));
        $survey = Survey::model()->findByPk($surveyId);

        $event->set(
            "surveysettings.{$this->id}",
            [
                'name' => get_class($this),
                'settings' => [
                    'errorText' => [
                        'type' => 'text',
                        'label' => $this->gT('Error text'),
                        'localized' => true,
                        'language' => $survey->getAllLanguages(),
                        // صفيف مفهرس برمز اللغة، مثال: ['en' => '...', 'de' => '...']
                        'current' => $this->get('errorText', 'Survey', $surveyId, []),
                    ],
                ]
            ]
        );
    }

القيمة المرسلة هي صفيف مفهرس برمز اللغة، لذلك تقوم الدالة newSurveySettings من المثال أعلاه بحفظها دون أي تغيير. لقراءة النص الخاص باللغة الحالية:

$errorTexts = $this->get('errorText', 'Survey', $surveyId, []);
$errorText = $errorTexts[App()->getLanguage()] ?? '';

الأحداث

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

واجهة برمجة التطبيقات (API)

يجب أن تقوم البرامج المساعدة بتوسيع LimeSurvey عبر واجهة API "العامة" فقط. هذا يعني أن استخدام الفئات الموجودة في الشيفرة المصدرية مباشرةً ممارسة غير سليمة. ورغم أننا لا نستطيع منعك من ذلك، فإنك تخاطر بتعطل البرنامج المساعد مع كل تحديث طفيف نقوم به.

تفاعل مع LimeSurvey قدر الإمكان عبر الطرق الموضحة هنا فقط. وينطبق الأمر نفسه على الأحداث.

كائن API متاح عبر $this->api عند الوراثة من PluginBase، وإلا يمكنك الحصول عليه من نسخة PluginManager التي يتم تمريرها إلى مُنشئ البرنامج المساعد الخاص بك.

يمكن إضافة دوال جديدة إلى كائن API عند الطلب.

<span id="Form_extension ^{(New in 6 )}">

امتداد النماذج ^{(New in 6 )}

مقدمة

نظام امتداد النماذج هو طريقة أكثر عمومية لتوسيع النماذج في نواة LimeSurvey دون إضافة حدث جديد لكل نموذج.

يتكون من المكونات التالية:

• وحدة عامة تسمى FormExtensionService
• مكتبة من فئات الإدخال يمكن للبرامج المساعدة إضافتها إلى تهيئة الوحدة المذكورة أعلاه
• أداة (widget) مع عارضات مخصصة، تُستخدم في ملفات العرض الخاصة بـ LimeSurvey

يتم تعريف كل نموذج بواسطة سلسلة موضع مثل <form name><dot><tab name>. مثال: globalsettings.general أو globalsettings.security.

الغرض من النظام القائم على الفئات دون HTML هو تحرير مؤلفي البرامج المساعدة من عناء تحديث HTML عند تغيّر HTML في النواة. ومع ذلك، يمكن للمؤلف استخدام النوع RawHtmlInput عند الحاجة.

هناك أمر واحد لا يمكنك القيام به في هذا النظام وهو إضافة علامات تبويب جديدة للنماذج.

مثال

لإضافة حقل إدخال جديد إلى نموذج من برنامج مساعد، استخدم الشيفرة التالية من الدالة init() الخاصة بك:

TODO: الحفظ في إعدادات البرنامج المساعد بدلًا من الإعدادات العامة

// At top of file
use LimeSurvey\Libraries\FormExtension\Inputs\TextInput;
use LimeSurvey\Libraries\FormExtension\SaveFailedException;

// Inside init()
Yii::app()->formExtensionService->add(
    'globalsettings.general',
    new TextInput([
        'name' => 'myinput',
        'label' => 'Label',
        'disabled' => true,
        'tooltip' => 'Moo moo moo',
        'help' => 'Some help text',
        'save' => function($request, $connection) {
            $value = $request->getPost('myinput');
            if ($value === 'some invalid value') {
                throw new SaveFailedException("Could not save custom input 'myinput'");
            } else {
                SettingGlobal::setSetting('myinput', $value);
            }
        },
        'load' => function () {
            return getGlobalSetting('myinput');
        }
    ])
);

التحقق من الصحة

يتم التحقق من صحة المدخلات في الدالة save (انظر المثال أعلاه). إذا كانت القيمة المرسلة غير صالحة، فقم بإطلاق الاستثناء SaveFailedException، وستظهر للمستخدم رسالة تحذير فورية.

النماذج المدعومة

يمكن توسيع النماذج التالية:

• globalsettings.general ^{(New in 6.0.0 )}

إذا كنت ترغب في إضافة دعم لنموذج أساسي آخر، فعليك تطبيق التغيير التالي في طلب سحب (pull request):

في ملف العرض، أضف:

<?php
use LimeSurvey\Libraries\FormExtension\FormExtensionWidget;
use LimeSurvey\Libraries\FormExtension\Inputs\DefaultBaseRenderer;
?>
... more HTML
<?= FormExtensionWidget::render(
    App()->formExtensionService->getAll('globalsettings.security'),
    new DefaultBaseRenderer()
); ?>

قد يتعين عليك إنشاء فئة عارض (renderer) جديدة تعتمد على DefaultBaseRenderer إذا كان HTML الخاص بالنموذج يختلف عن النماذج الأخرى. وقد تحتاج أيضًا إلى توسيع فئة العارض الافتراضية بأنواع إدخال لم تتم إضافتها بعد.

التغيير الثاني الذي عليك القيام به هو إضافة استدعاء لفئة خدمة امتداد النماذج في إجراء المتحكم (controller) الذي يحفظ النموذج:

$request = App()->request;
Yii::app()->formExtensionService->applySave('globalsettings', $request);

هذا كل شيء!

<span id="Localization_ ^{(New in 3 )}">

التوطين ^{(New in 3 )}

يمكن للبرامج المساعدة إضافة ملفات اللغة الخاصة بها. صيغة الملف المستخدمة هي .mo، وهي نفسها المستخدمة في ترجمات النواة. يجب تخزين الملفات في:

<plugin root folder>/locale/<language>/<language>.mo

حيث "<language>" هو رمز من حرفين مثل "de" أو "fr".

لاستخدام ملف اللغة الخاص بالبرنامج المساعد، استخدم دالة البرنامج المساعد gT:

$this->gT("A plugin text that needs to be translated");

إذا تعذر العثور على النص المعطى في ملف اللغة الخاص بالبرنامج المساعد، فستبحث الدالة في ملفات اللغة الأساسية. لذلك يمكنك بأمان استخدام نصوص مثل "Cancel":

$this->gT("Cancel");  // Will be translated even if "Cancel" is not in the plugin locale file

إذا كنت تستخدم ملفات العرض مع البرنامج المساعد الخاص بك، فعليك استخدام:

$plugin->gT("Translate me");

لإجراء ترجمة خاصة بالبرنامج المساعد في العرض الخاص بك.

يمكنك استخدام الملف limesurvey.pot كمثال على شكل ملف pot. يتم استيراد هذا الملف إلى أداة الترجمة الخاصة بك.

الأدوات

إحدى الأدوات مفتوحة المصدر لتحرير ملفات po وmo هي Poedit.

<span id="Logging_ ^{(New in 3 )}">

التسجيل ^{(New in 3 )}

إذا كنت ترغب في تسجيل شيء ما من البرنامج المساعد الخاص بك، فاكتب ببساطة:

$this->log("Your message");

مستوى التسجيل الافتراضي هو trace، ولكن يمكنك تحديد مستوى تسجيل آخر كوسيط ثانٍ اختياري:

$this->log("Something went wrong!", CLogger::LEVEL_ERROR);

يمكنك العثور على ملف السجل في المجلد

<limesurvey root folder>/tmp/runtime/plugin.log

يُستخدم اسم البرنامج المساعد الخاص بك تلقائيًا كفئة. من الطرق الجيدة لعرض الأخطاء الصادرة من البرنامج المساعد فقط استخدام grep (على Linux):

 $ tail -f tmp/runtime/plugin.log | grep <your plugin name>

<span id="Logging_plugin_deactivation_due_to_error_ ^{(New in 6.13.3 )}">

تسجيل إلغاء تنشيط البرنامج المساعد بسبب خطأ ^{(New in 6.13.3 )}

منذ الإصدار 5 من LimeSurvey: يمكن إلغاء تنشيط البرنامج المساعد تلقائيًا عند حدوث خطأ في PHP.

يتم إرسال بريد إلكتروني تلقائيًا إلى مدير LimeSurvey. يمكنك استخدام نظام السجل لإنشاء تنبيه لمديري الخوادم الآخرين.

على سبيل المثال: لإرسال رسالة تنبيه

                // حدث خطأ في البرنامج المساعد وتم تعطيله: إرسال بريد إلكتروني باستخدام CLogRoute
                'pluginError' => array(
                    'class' => 'CEmailLogRoute', // https://www.yiiframework.com/doc/api/1.1/CEmailLogRoute
                    'categories' => 'application.model.plugin.setLoadError', // تم تعطيل برنامج مساعد
                    'subject' => '[ERROR] Plugin deactivated',
                    'emails' => ['webmaster@example.org'],
                    'sentFrom' => 'noreply@example.org',
                    'enabled' => 1, // مفعّل هنا
                )

مزيد من المعلومات حول إعداد التسجيل في Yii 1: إعدادات التسجيل.

<span id="Extension_updates_ ^{(New in 4 )}">

تحديثات الامتدادات ^{(New in 4 )}

منذ نسخة LimeSurvey 4.0.0، يوجد نظام للتعامل مع تحديثات البرامج المساعدة والامتدادات الأخرى. لاستخدام هذا النظام، يجب أن يتضمن ملف config.xml الخاص بالامتداد إعدادات المحدّث.

<updaters>
    <updater>
        <stable>1</stable>
        <type>rest</type>
        <source>https://comfortupdate.limesurvey.org/index.php?r=limestorerest</source>
        <manualUpdateUrl>https://somedownloadlink.com/maybegithub</manualUpdateUrl>
    </updater>
</updaters>

(تشير العلامة source أعلاه إلى واجهة LimeStore REST API، وسيتم استخدامها لجميع الامتدادات المتوفرة في LimeStore.)

وصف علامات المحدّث

العلامة	وصف
stable	"1" إذا كان هذا المصدر يوفر أرقام نسخ مستقرة فقط؛ "0" إذا كان المصدر سيوفر أيضًا نسخًا غير مستقرة، مثل 0.3.3-beta.
type	حاليًا، النوع rest فقط مدعوم. من السهل إضافة أنواع جديدة من المحدّثات (أدوات التحقق من النسخ)، مثل git وwget وغيرها.
source	عنوان URL الذي يتم جلب النسخ الجديدة منه.
manualUpdateUrl	عنوان URL الذي يمكن للمستخدم الانتقال إليه لتحديث الامتداد إلى أحدث نسخة.
automaticUpdateUrl	TODO

إذا لم ترغب في توفير محدّث، فيجب أن تضع النص التالي في ملف XML الخاص بالإعدادات:

<updaters disabled="disabled">
</updaters>

بهذه الطريقة، تُعلم النظام بأنك عطّلت نظام التحديث عن قصد، وأنك لم تنسَ إضافته فحسب.

يقوم البرنامج المساعد الجديد UpdateCheck - المثبّت والمفعّل افتراضيًا - بالتحقق من وجود تحديثات جديدة لـكل الامتدادات المثبتة عند تسجيل دخول المدير العام، بشكل غير متزامن، وبحد أقصى مرة واحدة كل 24 ساعة. إذا تم العثور على أي نسخ جديدة، يتم إرسال إشعار.

إذا تم العثور على تحديث أمان جديد، فسيُفتح الإشعار تلقائيًا ويُعرض بنمط الفئة "danger".

يمكنك التحقق من وجود تحديثات يدويًا بالانتقال إلى عرض مدير البرامج المساعدة والنقر على "Check updates". لاحظ أن هذا الزر لا يظهر إلا إذا كان البرنامج المساعد UpdateCheck مفعّلًا.

ما وراء الكواليس

يقدم هذا القسم نظرة عامة موجزة على تنفيذ محدّث الامتدادات.

محدّث الامتدادات جزء من مكتبة ExtensionInstaller. فيما يلي مخطط UML للفئات المرتبطة بعملية التحديث.

سير البرنامج عند بدء تشغيل Yii:

 Yii init
   VersionFetcherServiceLocator->init()
     Add REST version fetcher
   ExtensionUpdaterServiceLocator->init()
     Add PluginUpdater
     TODO: Add an updater for each extension type (theme, question template, ...)

تدفق البرنامج عند تشغيل البرنامج المساعد UpdaterCheck:

 Get all updaters from ExtensionUpdaterServiceLocator
 Loop each updater
   For each updater, loop through version fetchers configured by <updater> XML
     For each version fetcher, contact remote source and get version information
 Compose all versions into a notification

توفر الطريقة checkAll في البرنامج المساعد UpdateCheck مثالًا على كيفية الاستعلام عن الإصدارات الجديدة لجميع الامتدادات.

إضافة أدوات جلب إصدارات جديدة

لإضافة أداة مخصصة جديدة لجلب الإصدارات، نفّذ الكود التالي أثناء تهيئة Yii:

$service = \Yii::app()->versionFetcherServiceLocator
$service->addVersionFetcherType(
  'myNewVersionFetcherType',
  function (\SimpleXMLElement $updaterXml) {
    return new MyNewVersionFetcher($updaterXml);
  }
);

بالطبع، يجب أن يكون الصنف MyNewVersionFetcher صنفًا فرعيًا من VersionFetcher.

لاستخدام أداة جلب الإصدارات الجديدة، قم بضبط الوسم type في ملف XML الخاص بالمحدّث ليستخدم myNewVersionFetcherType (بدلًا من rest مثلًا).

إضافة أدوات تحديث امتدادات جديدة

لإضافة أداة تحديث امتداد مخصصة جديدة، نفّذ الكود التالي أثناء تهيئة Yii:

$service = \Yii::app()->extensionUpdaterServiceLocator;
$service->addUpdaterType(
  'myNewExtensionUpdater',
  function () {
    return MyNewExtensionUpdater::createUpdaters();
  }
);

يجب أن يكون الصنف MyNewExtensionUpdater صنفًا فرعيًا من ExtensionUpdater.

سيحدد الوسم type في المستوى الأعلى من ملف config.xml ('plugin' أو 'theme' ...) أداة تحديث الامتداد المستخدمة لهذا الامتداد. النظام غير قابل للتخصيص بالكامل بعد، لأنك تحتاج أيضًا إلى إضافة ExtensionInstaller مخصص وعناصر قائمة وغيرها. لكن من الناحية النظرية، وربما في المستقبل، سيكون من الممكن إضافة نوع جديد من الامتدادات بهذه الطريقة.

مثبّت الامتدادات

تتكون مكتبة مثبّت الامتدادات من صنفين مجرّدين:

• ExtensionInstaller
• FileFetcher

يتم اشتقاق صنف فرعي من ExtensionInstaller لكل نوع من الامتدادات، مثل PluginInstaller وQuestionThemeInstaller وغيرها.

يتم اشتقاق صنف فرعي من FileFetcher لكل طريقة مختلفة لجلب الملفات. حاليًا، لا يتم دعم سوى ملفات zip المرفوعة، ولكن في المستقبل قد تتوفر أداة جلب من Github أو LimeStore أيضًا.

دليل تعليمي

يوضح هذا الدليل التعليمي خطوة بخطوة كيفية إنشاء برنامج مساعد يرسل طلب post عند كل إرسال لرد على الاستبيان. كما يوضح كيفية إنشاء وحفظ الإعدادات العامة وإعدادات كل استبيان، وكيفية تسجيل الأحداث وغير ذلك.