Artilugios¶

Los artilugios son zonas de contenido que los usuarios pueden arrastrar por su página para personalizar su disposición. Normalmente su dueño puede personalizarlos para mostrar más o menos contenido, y controlar quien puede verlos. De manera predeterminada, Elgg ofrece complementos para personalizar la página de perfil y de inicio mediante artilugios.

Por hacer: captura de pantalla.

Contents

Estructura
Register the widget
Default widgets

Estructura ¶

Para crear un artilugio, cree dos vistas:

widgets/widget/edit
widgets/widget/content

content.php is responsible for all the content that will output within the widget. The edit.php file contains any extra edit functions you wish to present to the user. You do not need to add access level as this comes as part of the widget framework.

Nota

Using HTML checkboxes to set widget flags is problematic because if unchecked, the checkbox input is omitted from form submission. The effect is that you can only set and not clear flags. The «input/checkboxes» view will not work properly in a widget’s edit panel.

Register the widget ¶

Once you have created your edit and view pages, you need to initialize the plugin widget. This is done within the plugins init() function.

// Add generic new file widget
elgg_register_widget_type([
    'id' => 'filerepo',
    'name' => elgg_echo('widgets:filerepo:name'),
    'description' => elgg_echo('widgets:filerepo:description'),
]);

Nota

The only required attribute is the id.

Varios artilugios ¶

It is possible to add multiple widgets for a plugin. You just initialize as many widget directories as you need.

 // Add generic new file widget
 elgg_register_widget_type([
     'id' => 'filerepo',
     'name' => elgg_echo('widgets:filerepo:name'),
     'description' => elgg_echo('widgets:filerepo:description'),
 ]);

 // Add a second file widget
elgg_register_widget_type([
     'id' => 'filerepo2',
     'name' => elgg_echo('widgets:filerepo2:name'),
     'description' => elgg_echo('widgets:filerepo2:description'),
 ]);

 // Add a third file widget
elgg_register_widget_type([
     'id' => 'filerepo3',
     'name' => elgg_echo('widgets:filerepo3:name'),
     'description' => elgg_echo('widgets:filerepo3:description'),
 ]);

Make sure you have the corresponding directories within your plugin views structure:

'Plugin'
    /views
        /default
            /widgets
               /filerepo
                  /edit.php
                  /content.php
               /filerepo2
                  /edit.php
                  /content.php
               /filerepo3
                  /edit.php
                  /content.php

How to restrict where widgets can be used ¶

The widget can specify the context that it can be used in (all, just profile, just dashboard, etc.). If you do not specify a context they will be available for all contexts.

elgg_register_widget_type([
    'id' => 'filerepo',
    'context' => ['profile', 'dashboard', 'other_context'],
]);

Allow multiple widgets on the same page ¶

By default you can only add one widget of the same type on the page. If you want more of the same widget on the page, you can specify this when registering the widget:

elgg_register_widget_type([
    'id' => 'filerepo',
    'multiple' => true,
]);

Register widgets in a hook ¶

If, for example, you wish to conditionally register widgets you can also use a hook to register widgets.

function my_plugin_init() {
    elgg_register_plugin_hook_handler('handlers', 'widgets', 'my_plugin_conditional_widgets_hook');
}

function my_plugin_conditional_widgets_hook($hook, $type, $return, $params) {
    if (!elgg_is_active_plugin('file')) {
        return;
    }

    $return[] = \Elgg\WidgetDefinition::factory([
        'id' => 'filerepo',
    ]);

    return $return;
}

Modify widget properties of existing widget registration ¶

If, for example, you wish to change the allowed contexts of an already registered widget you can do so by re-registering the widget with elgg_register_widget_type as it will override an already existing widget definition. If you want even more control you can also use the handlers, widgets hook to change the widget definition.

function my_plugin_init() {
    elgg_register_plugin_hook_handler('handlers', 'widgets', 'my_plugin_change_widget_definition_hook');
}

function my_plugin_change_widget_definition_hook($hook, $type, $return, $params) {
    foreach ($return as $key => $widget) {
        if ($widget->id === 'filerepo') {
            $return[$key]->multiple = false;
        }
    }

    return $return;
}

Default widgets ¶

Si su complemento utiliza el canvas del artilugio, puede registrar que ofrece artilugios predeterminados en el núcleo de Elgg, para dejar que Elgg se ocupe de todo lo demás.

Para anunciar que su complemento ofrece artilugios predeterminados, registre un manejador para el gancho de complementos get_list, default_widgets:

elgg_register_plugin_hook_handler('get_list', 'default_widgets', 'my_plugin_default_widgets_hook');

En el manejador, devuelva un vector que indique que ofrece artilugios predeterminados y cuándo crear los artilugios predeterminados. El vector puede contener las siguientes claves:

name es el nombre de la página de artilugios. Ésta se muestra en la pestaña de la interfaz de administración.
widget_context es el contexto desde el que se llama a la página de artilugios. Si no se indica de manera explícita, su valor será el identificador del complemento.
widget_columns es el número de columnas que usará la página de artilugios.
event - The Elgg event to create new widgets for. This is usually create.
entity_type es el tipo de la entidad para la que crear los nuevos artilugios.
entity_subtype es el subtipo de la entidad para la que crear los nuevos artilugios. Su valor puede ser ELGG_ENTITIES_ANY_VALUE para crearlo para todos los tipos de entidad.

Cuando un objeto desencadena un evento que coincide con el valor de los parámetros event, entity_type y entity_subtype que se pasen, el núcleo de Elgg buscará artilugios predeterminados que coincidan con el valor de widget_context indicado, y los copiará en las propiedades owner_guid y container_guid del objeto. También se copiará la configuración del artilugio.

function my_plugin_default_widgets_hook($hook, $type, $return, $params) {
    $return[] = array(
        'name' => elgg_echo('my_plugin'),
        'widget_context' => 'my_plugin',
        'widget_columns' => 3,

        'event' => 'create',
        'entity_type' => 'user',
        'entity_subtype' => ELGG_ENTITIES_ANY_VALUE,
    );

    return $return;
}