Example Wiki Widget

From Hexten

To get you started writing your own Wiki Widgets we'll walk through the creation of the canonical Hello World Widget. Before starting you need to have Wiki Widgets installed on your Wiki. Read Installing Wiki Widgets if you haven't yet done that.

Contents 1 Create a directory 2 Create the files 2.1 init.php 2.2 helloworld.php 3 Further reading

[edit] Create a directory

Widgets live in the directory /wiki/extensions/wx/widget (replace /wiki with the installation path of your wiki). Widget names are like variable names - they should contain only letters, digits and underscores. By convention widget names are lower case. Remember that MediaWiki might be installed on a case insensitive filesystem so you shouldn't rely on case differences to distinguish between different widgets.

We'll call our widget 'helloworld' so create the directory

 /wiki/extensions/wx/widget/helloworld

[edit] Create the files

When loading a widget Wiki Widgets looks for a file called

 /wiki/extensions/wx/widget/widget name/init.php
 

In this case that will be

 /wiki/extensions/wx/widget/helloworld/init.php

Create that file now and open it in an editor.

[edit] init.php

A Widget's init.php is responsible for including any other PHP source the extension needs. The implementation of our Widget is going to be a PHP class called HelloWorldWidget so we'll put it in a file called helloworld.php. We'll include (actually require) that now. Add this line to your init.php

 require_once(dirname(__FILE__) . "/helloworld.php");

Next init.php needs to add the widget to the list of widgets Wiki Widgets knows about. Add the following lines:

 wxAddWidget('helloworld', array(
     'class'  => 'HelloWorldWidget',
 ));

wxAddWidget() declares a widget. In this case the widget is called 'helloworld' and it's implementation is contained in a class called 'HelloWorldWidget'.

That's all we need in init.php just now. Later we can add options that will be supplied to the Widget when it's loaded.

[edit] helloworld.php

The main work of the Widget is done by an instance of HelloWorldWidget. Create helloworld.php now and add the following code to it.

 
  class HelloWorldWidget extends WikiWidget {
      function meta() {
          return array(
              'name'          => 'Hello World Widget',
              'description'   => 'Say Hello',
              'author'        => 'Andy Armstrong',
              'url'           => array(
                  'Example Wiki Widget' =>
                  'http://hexten.net/wiki/index.php?title=Example_Wiki_Widget'
              ),
              'version'       => '0.1',
              'example'       => array(),
          );
      }

      function render() {
          $this->output(
              $this->tag('p', 'Hello, World!')
          );
      }
  }
  

And that's it. Try it out now. Create a new page in your wiki and add the markup

 
  <widget />
  

When you preview the page you should see a list of installed widgets including Hello World Widget. Notice that the information returned by meta() is turned into an about box for the widget.

Now change your test page to

 
  <widget type="helloworld" />
  

and hit Preview again. Now you should see the message 'Hello, World!' that your widget outputs.

[edit] Further reading

• Extending Hello World - extending the helloworld widget
• Wiki Widgets API - API documentation