Complementos - avanzado
From LimeSurvey Manual
Descripción general
A partir de LimeSurvey 2.05, LimeSurvey admitirá oficialmente complementos. Algunos complementos serán compatibles con el equipo de LimeSurvey y se incluirán en el núcleo. Algunos contarán con el apoyo de otros fuera del equipo de LimeSurvey. Para ayudarlo a encontrarlos, consulte los Complementos de terceros disponibles y agréguele su propio complemento.
Los complementos permiten a los usuarios personalizar la funcionalidad de su instalación y al mismo tiempo beneficiarse de las actualizaciones periódicas de software.
Esta documentación está destinada a desarrolladores que están ampliando LimeSurvey para su propio uso o para sus clientes; Esta documentación no ayudará a los usuarios finales.
Los complementos deben implementar la interfaz iPlugin. Recomendamos ampliar su clase de complemento desde la clase PluginBase.
Los complementos se desarrollan en torno a un mecanismo de event.
Configuración del complemento
Al ampliar, se beneficia de la funcionalidad común requerida por los complementos que ya hemos implementado para usted. Una de estas funciones es la implementación de la función getPluginSettings. Esta función debe devolver una matriz que describa las opciones de configuración para el usuario.
El complemento de ejemplo expone solo 1 configuración configurable, el mensaje que mostrará.
protegted $configuración = matriz(
'logo' => matriz(
'tipo' => 'logotipo',
'ruta' => 'assets/logo.png'
) ,
'mensaje' => matriz(
'tipo' => 'cadena',
'etiqueta' => 'Mensaje'
)
);
La matriz contiene un nombre para cada configuración como clave. Los valores son matrices que contienen los metadatos requeridos.
Los tipos admitidos son:
- logo
- int (número entero)
- cadena (alfanumérica)
- texto
- html
- relevancia
- info
- contraseña
- fecha!
- seleccionar
Además de escribir, hay otras claves disponibles:
- etiqueta, define una etiqueta
- predeterminado, define un valor para mostrar si no se especifica ningún valor (solo para la configuración global, no para la configuración de la encuesta)
- actual, define el valor actual.
- solo lectura: se muestra la configuración como ¡solo lectura
- htmlOptions, las htmlOptions de la parte de entrada (consulte el manual de Yii [[1]])
- pluginOptions, para algunas configuraciones (html o select): establece la opción del widget
- labelOptions: htmlOptions de la etiqueta
- controlOptions: htmlOptions del contenedor de etiqueta y entrada
Puede encontrar un ejemplo de complemento utilizando todas las configuraciones reales en exampleSettings
Leer y escribir configuraciones de complemento
Es posible leer y escribir la configuración del complemento directamente desde el código del complemento.
Ejemplo:
$miConfiguración = $this->get('miConfiguración');
$this->set('miConfiguración', $miConfiguración + 1);
Puede obtener un valor predeterminado si la configuración es nula:
$miConfiguración = $this->get('miConfiguración', nulo, nulo, 10); // ¡10 es el valor predeterminado
Survey specific plugin settings
Two events are used to create survey specific plugin settings:
- newSurveySettings
- beforeSurveySettings
Example to disable a plugin for a specific survey:
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);
}
Eventos
Los complementos se suscriben a eventos y pueden interactuar con LimeSurvey cuando se activa el evento. Para obtener una lista de los eventos disponibles actualmente, consulte Eventos complementarios.
API
Los complementos sólo deberían extender LimeSurvey a través de su API "pública". Esto significa que usar directamente las clases que se encuentran en el código fuente es una mala práctica. Aunque no podemos obligarte a no hacerlo, corres el riesgo de tener un complemento roto con cada actualización menor que hacemos.
En la medida de lo posible, interactúe con LimeSurvey solo a través de los métodos descritos aquí. Lo mismo que para eventos.
El objeto API está disponible a través de $this->api cuando se extiende desde PluginBase; de lo contrario, puede obtenerlo desde la instancia de PluginManager que se pasa al constructor de sus complementos.
Se pueden agregar nuevas funciones al objeto API a pedido.
Extensión de formulario (New in 6 )
Introducción
El sistema de extensión de formularios es una forma más general de ampliar formularios en el núcleo de LimeSurvey sin agregar un nuevo evento para cada formulario.
Consta de los siguientes componentes:
- ¡Un módulo global llamado FormExtensionService
- ¡Una biblioteca de clases de entrada que los complementos pueden agregar a la inicialización del módulo anterior
- Un widget, junto con renderizadores personalizados, que se utilizan en los archivos de vista de LimeSurvey
Cada formulario se identifica mediante una cadena de posición, como<form name><dot><tab name> . Ejemplo: globalsettings.general o globalsettings.security .
El objetivo detrás de un sistema basado en clases sin HTML es liberar a los autores del complemento del trabajo para actualizar el HTML cuando cambia el HTML principal. Aún así, el autor puede utilizar el tipo RawHtmlInput si es necesario.
Una cosa que no puede hacer en este sistema es agregar "nuevas pestañas de formulario".
Ejemplo
Para agregar una nueva entrada a un formulario desde un complemento, use el siguiente código de su función init():
TODO: Guardar en la configuración del complemento en lugar de global
// En la parte superior del archivo
use LimeSurvey\Libraries\FormExtension\Inputs\TextInput;
use LimeSurvey\Libraries\FormExtension\SaveFailedException;
// Dentro de init()
Yii::app()->formExtensionService->add(
'globalsettings.general',
new TextInput([
'name' => 'myinput',
'label' => 'Etiqueta',
'disabled' => true,
'tooltip' => 'Moo moo moo',
'help' => 'Algún texto de ayuda',
'save' => function($solicitud, $conexión) {
$valor = $solicitud->getPost('myinput');
if ($value === 'algún valor no válido') {
throw new SaveFailedException("No se pudo guardar la entrada personalizada 'myinput'");
} else {
ConfiguraciónGlobal::setSetting('myinput', $value);
}
} ,
'load' => function () {
return getGlobalSetting('myinput');
}
])
);
Validación
La validación de la entrada se realiza en la función save (ver ejemplo arriba). Si el valor publicado no es válido, lanza una SaveFailedException y se mostrará al usuario un mensaje flash de advertencia.
Formularios admitidos
Se pueden ampliar las siguientes formas:
- configuración global.general (New in 6.0.0 )
Si desea agregar soporte para otro formulario principal, debe aplicar el siguiente cambio en una solicitud de extracción:
En el archivo de vista, agregue:
!¡NORTE! <?php
use LimeSurvey\Libraries\FormExtension\FormExtensionWidget;
use LimeSurvey\Libraries\FormExtension\Inputs\DefaultBaseRenderer;
?>
... más HTML
<?= FormExtensionWidget::render(
App()-> formExtensionService->getAll('globalsettings.security'),
nuevo DefaultBaseRenderer()
); ?>
Es posible que tengas que crear una nueva clase de renderizador basada en DefaultBaseRenderer , si el formulario HTML es diferente a otros formularios. Es posible que también necesite ampliar la clase de renderizador predeterminada con tipos de entrada que aún no se han agregado.
El segundo cambio que debe hacer es agregar una llamada a la clase de servicio de extensión de formulario en la acción del controlador que guarda el formulario:
$request = App()->request;
Yii::app()->formExtensionService->applySave('globalsettings', $request);
¡Eso es todo!
Localización (New in 3 )
Es posible que los complementos agreguen sus propios archivos locales. El formato de archivo utilizado es .mo, igual que las traducciones principales. Los archivos deben almacenarse en
<plugin root folder>/lugar/<language> /<language> .mes
dónde "<language> " es una palabra de dos letras como "de" o "fr".
Para usar el archivo local específico, use la función del complemento gT:
$this->gT("Un texto de complemento que debe traducirse");
Si la cadena proporcionada no se puede encontrar en el archivo local específico del complemento, la función buscará en los archivos locales principales. Por tanto, es seguro utilizar cadenas como "Cancelar":
$this->gT("Cancelar"); // ¡Se traducirá incluso si "Cancelar" no está en el archivo local del complemento
Si está utilizando vistas junto con su complemento, debe usar
$plugin->gT("Traducirme");
para hacer una traducción específica del complemento en su vista.
Puede utilizar el archivo limesurvey.pot como ejemplo de cómo puede verse un archivo pot. Esto se importa a su herramienta de traducción.
Herramientas
Una herramienta de código abierto para editar archivos po y mo es [2].
Iniciando sesión (New in 3 )
Si desea registrar algo desde su complemento, simplemente escriba
$this->log("Tu mensaje");
El nivel de registro predeterminado es rastreo, pero puede proporcionar otro nivel de registro como segundo argumento opcional:
$this->log("¡Algo salió mal!", CLogger::LEVEL_ERROR);
El archivo de registro se puede encontrar en la carpeta
<limesurvey root folder>/tmp/runtime/plugin.log
El nombre de su complemento se utiliza automáticamente como categoría. Una buena manera de ver solo los errores de su complemento es usar grep (en Linux):
$ cola -f tmp/runtime/plugin.log | grep<your plugin name>
Más información sobre cómo configurar el registro en Yii 1: Optional_settings#Logging_settings.
Actualizaciones de extensiones (New in 4 )
Desde la versión 4.0.0 de LimeSurvey, existe un sistema para gestionar las actualizaciones de complementos y otras extensiones. Para utilizar este sistema, su archivo de extensión config.xml debe incluir la configuración del actualizador.
<updaters> <updater>
<stable> 1</stable>
<type> descansar</type>
<source> https://comfortupdate.limesurvey.org/index.php?r=limestorerest</source>
<manualUpdateUrl> https://somedownloadlink.com/maybegithub</manualUpdateUrl>
</updater>
</updaters>
(La etiqueta fuente anterior apunta a la API REST de LimeStore, que se utilizará para todas las extensiones disponibles en nuestro LimeStore).
| Etiqueta | Descripción |
|---|---|
| estable | "1" si esta fuente sólo proporciona números de versión estables; "0" si la fuente también proporcionará versiones inestables, como 0.3.3-beta .
|
| escriba | Por ahora, solo se admite el tipo rest . ¡Es fácil agregar nuevos tipos de actualizadores (comprobadores de versiones), como git, wget, etc.
|
| fuente | La URL para obtener nuevas versiones. |
| manualUpdateUrl | URL a la que el usuario puede acceder para actualizar la última versión de la extensión. |
| URL de actualización automática | TODO |
Si no desea proporcionar un actualizador, debe colocar el siguiente texto en su archivo XML de configuración:
<updaters disabled="disabled">
</updaters>
De esta manera, le dice al sistema que deshabilitó intencionalmente el sistema de actualización y que no se olvidó de agregarlo.
El nuevo complemento UpdateCheck, instalado y activado de forma predeterminada, busca nuevas actualizaciones para todas las extensiones instaladas cuando un superadministrador inicia sesión, de forma asincrónica, como máximo una vez cada 24 horas. Si se encuentra alguna versión nueva, se envía una notificación.
Si se encuentra una nueva actualización de seguridad, la notificación se abrirá automáticamente y tendrá el estilo de clase "peligro".
Puede buscar actualizaciones manualmente yendo a la vista del administrador de complementos y haciendo clic en "Verificar actualizaciones". Tenga en cuenta que este botón solo es visible si el complemento UpdateCheck está activado.
Debajo del capó
Esta sección proporciona una breve descripción general de la implementación del actualizador de extensiones.
El actualizador de extensiones es parte de la biblioteca ExtensionInstaller. A continuación se muestra un diagrama UML para las clases relacionadas con el proceso de actualización.
Flujo del programa cuando se inicia Yii:
Yii inicio VersionFetcherServiceLocator->init() ¡Agregue el buscador de versiones REST ExtensionUpdaterServiceLocator->init() Añadir PluginUpdater TODO: ¡Agregue un actualizador para cada tipo de extensión (tema, plantilla de pregunta,...)
Flujo del programa al ejecutar el complemento UpdaterCheck:
Obtenga todos los actualizadores de ExtensionUpdaterServiceLocator ¡Repita cada actualizador Para cada actualizador, recorra los buscadores de versiones configurados por<updater> XML Para cada buscador de versiones, comuníquese con la fuente remota y obtenga información sobre la versión. ¡Componga todas las versiones en una notificación
El método checkAll en el complemento UpdateCheck proporciona un ejemplo de cómo consultar todas las extensiones para obtener nuevas versiones. .
Agregar nuevos buscadores de versiones
Para agregar un nuevo buscador de versiones personalizado, ejecute esto durante la inicialización de Yii:
$service = \Yii::app()->versionFetcherServiceLocator
$service->addVersionFetcherType(
'myNewVersionFetcherType',
function (\SimpleXMLElement $updaterXml) {
return new MyNewVersionFetcher( $updaterXml);
}
);
Por supuesto, la clase MyNewVersionFetcher tiene que ser una subclase VersionFetcher.
Para usar su nuevo buscador de versiones, configure la etiqueta type en el XML del actualizador para usar
myNewVersionFetcherType(en lugar de, por ejemplo,rest).
Agregar nuevos actualizadores de extensiones
Para agregar un nuevo actualizador de extensión personalizado, ejecute esto durante la inicialización de Yii:
$servicio = \Yii::app()->extensionUpdaterServiceLocator;
$servicio->addUpdaterType(
'myNewExtensionUpdater',
function () {
return MyNewExtensionUpdater::createUpdaters() ;
}
);
La clase MyNewExtensionUpdater tiene que ser una subclase ExtensionUpdater.
La etiqueta type superior en config.xml ('complemento', 'tema', ...) controlará qué actualizador de extensión se utiliza para esta extensión. El sistema aún no es completamente personalizable, ya que también es necesario agregar un ExtensionInstaller personalizado, elementos de menú, etc. Pero en teoría, y tal vez en el futuro, debería ser posible agregar un nuevo tipo de extensión de esta manera.
Instalador de extensiones
La biblioteca del instalador de extensiones consta de dos clases abstractas:
- ExtensionInstaller
- FileFetcher
ExtensionInstaller tiene subclases para cada tipo de extensión, como PluginInstaller, QuestionThemeInstaller, etc.
FileFetcher tiene subclases para cada forma diferente de recuperar archivos. Actualmente, solo se admiten archivos zip cargados, pero en el futuro, también podría haber un buscador de Github o LimeStore.
Complementos especiales
Complementos disponibles
Tutorial
Este tutorial paso a paso muestra cómo crear un complemento que envíe una solicitud de publicación en cada respuesta de la encuesta envío. El tutorial le muestra cómo crear y guardar configuraciones globales y por encuesta, cómo registrar eventos y más.