Widgets

Widgets are content areas that users can drag around their page to customize the layout. They can typically be customized by their owner to show more/less content and determine who sees the widget. By default Elgg provides plugins for customizing the profile page and dashboard via widgets.

Structure

To create a widget, create two views:

  • 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.

Note

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.

The easiest way to do this is to add the widgets section to your elgg-plugin.php config file.

return [
        'widgets' => [
                'filerepo' => [
                        'context' => ['profile'],
                ],
        ]
];

Alternatively you can also use an function to add a 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'),
    'context' => ['profile'],
]);

Note

The only required attribute is the id.

Multiple widgets

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'),
     'context' => ['profile'],
 ]);

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

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

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

Magic widget name and description

When registering a widget you can omit providing a name and a description. If a translation in the following format is provided, they will be used. For the name: widgets:<widget_id>:name and for the description widgets:<widget_id>:description. If you make sure these translation are available in a translation file, you have very little work registering the widget.

elgg_register_widget_type(['id' => 'filerepo']);

How to restrict where widgets can be used

The widget can specify the context that it can be used in (just profile, just dashboard, etc.).

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

If your plugin uses the widget canvas, you can register default widget support with Elgg core, which will handle everything else.

To announce default widget support in your plugin, register for the get_list, default_widgets plugin hook:

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

In the plugin hook handler, push an array into the return value defining your default widget support and when to create default widgets. Arrays require the following keys to be defined:

  • name - The name of the widgets page. This is displayed on the tab in the admin interface.
  • widget_context - The context the widgets page is called from. (If not explicitly set, this is your plugin’s id.)
  • widget_columns - How many columns the widgets page will use.
  • event - The Elgg event to create new widgets for. This is usually create.
  • entity_type - The entity type to create new widgets for.
  • entity_subtype - The entity subtype to create new widgets for. The can be ELGG_ENTITIES_ANY_VALUE to create for all entity types.

When an object triggers an event that matches the event, entity_type, and entity_subtype parameters passed, Elgg core will look for default widgets that match the widget_context and will copy them to that object’s owner_guid and container_guid. All widget settings will also be copied.

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;
}