Hello, World! Tutorial Overview

A plugin can do many things: add a photo gallery, change the color scheme of Elgg, or add a widget that displays the local weather. The tutorial will take you through the steps of creating a widget that will display "Hello, World!". Widgets are those components that you can drag onto your profile or dashboard.

This tutorial will assume that you have shell access to your server. If you don't, just create the files as described locally and ftp them to your server.

Please note that when you are developing plugins, it is best to turn off the simple cache and the view filepath cache. Otherwise, your changes may not always show up when you view your site. These controls can be found under Site Administration (for Elgg 1.6 and greater).

Registering your plugin

Plugins are always placed in the /mod directory. Create a subdirectory there called hello. This will be the name of your plugin and will show up in the Tools Administration section of Elgg by this name.

In /mod/hello, create an empty file called start.php. If this file exists, Elgg will load your plugin. Otherwise, you will see a misconfigured plugin error. Go to the admin section of your Elgg install and enable your plugin. Click on the "more info" link under your plugin name. You will notice that nothing happens.

Copy the manifest.xml file from one of the plugins in your elgg install into /mod/hello. Update its values so you are listed as the author and change the description to describe this new plugin. Reload the Tools Administration page in your browser and check "more info" again. It will now display the information that you've entered.

Adding the widget view code

Elgg automatically scans particular directories under plugins looking for particular files. This view system makes it easy to add your display code or do other things like override default Elgg behavior. For now, we will just be adding the view code for your widget. Create the directory structure /mod/hello/views/default/widgets/helloworld/. helloworld will be the name of your widget within the hello plugin.

In /mod/hello/views/default/widgets/helloworld/, create a file by the name view.php. In this file add the code

<div class="contentWrapper">
<?php echo 'hello, world!'; ?>
</div>

This will add these words to the widget canvas when it is drawn. Elgg takes care of loading the widget.

Registering your widget

Elgg needs to be told the plugin contains a widget so that it will scan the widget views directory. This is done through the add_widget_type() function. Edit /mod/hello/start.php. In it add these lines:

<?php
  function hello_init() {        
    add_widget_type('helloworld', 'My Widget', 'The hello, world widget');
  }
 
  register_elgg_event_handler('init','system','hello_init');       
?>

This code uses the Elgg event system to register the widget. Each time a page is loaded the init system event is thrown. The register_elgg_event_handler() function registers the function hello_init() as a handler of that event. The handler function registers the widget type so that it is available to users. Go to your profile using your web browser and add the 'My Widget' widget. You should see it display 'hello, world!'.

Handling multiple languages

Elgg also enables you to provide support for multiple languages. Create the directory /mod/hello/languages/. In that directory create the file en.php and add these lines

<?php
 
  $english = array(	
      'hello:greeting' => 'Hello!',	
      'hello:widget_name' => 'My Hello Widget',
	);
 
  add_translation("en",$english);
 
?>

The Elgg engine automatically scans languages directories under plugin directories so you do not need to register this file. To use these strings, edit your view.php file again so that it looks like this

<div class="contentWrapper">
<?php echo elgg_echo('hello:greeting'); ?>
</div>

You could also change start.php to use the localization string to name the widget by using this line

add_widget_type('helloworld', elgg_echo('hello:widget_name'), 'The hello, world widget');

Other languages can be added as described in the languages and internationalisation section.

Accept user input through widget edit

Click on the edit link on the toolbar of the widget that you've created. You will notice that the only control it gives you by default is over access (over who can see the widget).

Let's say that you want to allow the user to control what greeting is displayed in the widget. Just as Elgg automatically loads view.php when viewing a widget, it loads edit.php when a user clicks on edit on a widget. In /mod/hello/views/default/widgets/helloworld/, create a file of the name edit.php. In this file add the code

<p>Message: 
<?php 
    echo elgg_view('input/text', array( 'internalname' => 'params[message]', 
                                        'value' => $vars['entity']->message,
                                        'class' => 'hello-input-text', ) ); 
?>
</p>

This is calling the input/text view of Elgg. Elgg provides a set of input views: text, button, pulldown, checkboxes, email, etc. You can find the complete list in the directory /views/default/input/. These views create the html needed for form elements. In this case, we are adding a text input box. Using these views makes it easier to keep the look and feel of your site or plugins consistent. For more information on how the Elgg view system works, see Elgg view system.

Three variables are being passed to the input/text view: the name of the form input text box, a default value, and the css class that is assigned to the text box. The name of the input text box is params[message] because Elgg will automatically handle widget variables put in the array params. The actual php variable name will be message.

The reason we set the 'value' index of the array is so that the edit view remembers what the user typed in the previous time he changed the value of his Message text. This is done through the $vars array. Every view is passed the array $vars. This array contains all the variables the view needs. In this case, we are using the entity object that was passed to the edit view. This is an instance of the ElggWidget class that represents our widget. We are using the metadata variable message. Notice the relationship between the names of the internalname variable and the value.

Now to display the user's message we need to modify view.php to use this message variable. Edit view.php and change it to:

<div class="contentWrapper">
<?php echo $vars['entity']->message; ?>
</div>

You should now be able to enter a message in the text box and see it appear in the widget.