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.

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.

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.

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.

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.