Creating a gadget - Basic tutorial
In this tutorial we are going to build a very simple WordPress plugin that creates a Hello World gadget.
The gadget itself will be very limited in its functionality, but will serve as a building block for your own future gadgets.
Creating the plugin template
The first thing we will do is to create the template for a new plugin. More indepth instructions on WordPress plugin development can be found at the WordPress codex site.
If you are following along with the tutorial, create a new file in your favourite text editor called "helloworldgdaget.php" and paste the code below into it.
<?php
/*
Plugin Name: Hello World gadget
Plugin URI: http://dev.clearskys.net/MyDashboardGadgets/GadgetDevelopmentBasicTutorial
Description: This plugin is a basic Hello World dashboard gadget.
Version: 1.0
Author: clearskys.net
Author URI: http://blog.clearskys.net
*/
class helloworldgadget {
function helloworldgadget() {
// This is the creator function
}
// the rest of the plugin code will go here
}
$HWgadget =& new helloworldgadget();
?>
Adding our placeholder functions
The MyDashboard system requires that each gadget has a minimum of three functions, which are called at varying times depending on the way a user interacts with your gadget.
So our next step is to create the required functions within our plugin. Underneath the comment "the rest of the plugin code will go here", add the following lines of code. I will go through how and when each function is used when we add code to them below.
function create_my_gadget($args = false) {
}
function edit_my_gadget($args = false) {
}
function display_my_gadget($args = false) {
}
The gadget creation function
The gadget creation function is called when the user creates a new instance of your gadget by clicking on the "Add to page" link under your gadgets entry in the Gadget library.
It is used to setup any default and configuration values that your gadget may require.
As we don't need to set up any configuration at this time, we will just return True back to the MyDashboard system to show that the function has completed.
Change the create_my_gadget function to the following:
function create_my_gadget($args = false) {
// Do not want to do anything so just return true
return true;
}
Details on the more advanced features of the instance creation function can be found in The anatomy of a MyDashboard gadget.
The gadget edit settings function
The gadget edit settings function is called initially when the gadget is displayed on the dashboard page, and then again when the settings are updated by the user, so it needs to be able to handle both the display of stored settings and the update of any submitted settings.
In this case we do not have any settings that the user can change so we will simply return a message to the user that there aren't any editable settings.
Change the function edit_my_gadget function to the following:
function edit_my_gadget($args = false) {
// Return the information that there are no editable options.
return "No editable options.";
}
The edit settings function should always return HTML. It would usually return the content of an HTML form with any settings already selected and filled in. It shouldn't return the <FORM> tags, however as these are automatically created by the MyDashboard system.
Details on the more advanced features of the gadget editing function can be found in The anatomy of a MyDashboard gadget.
The gadget display function
This gadget display function is the main function for a gadget. It handles the display and main functionality for your gadget, so the code can get quite advanced.
For the purposes of this example we are going to display some basic information about your blog in the gadgets main display panel.
Change the function display_my_gadget function to the following:
function display_my_gadget($args = false) {
$mycontent = "Hello World<br/>";
$mycontent .= "Blog title : " . get_bloginfo('name') . "<br/>";
$mycontent .= "Blog desc : " . get_bloginfo('description') . "<br/>";
$mycontent .= "Blog url : " . get_bloginfo('url') . "<br/>";
$mycontent .= "WordPress version : " . get_bloginfo('version') . "<br/>";
$mytitle = "Hello World";
$mytitleicon = "";
return array( 'title' => $mytitle,
'titleicon' => $mytitleicon,
'content' => $mycontent
);
}
The display gadget returns a key=>value array containing the display information for the gadget. The array should contain three bits of information:
- title - The title is displayed in the header bar of your gadget. It can be a simple text heading or can include HTML items such as links, styles or images.
- titleicon - The titleicon should be an HTML <IMG> tag to display a small icon (the icon should be limited to 16pixels by 16 pixels in size). You can also wrap the <IMG> tag with a link so that it can link to alternate content than the title. A good example of this is the RSS Feed gadget where the title links to the web page for the feed and the icon links to the feed itself.
- content - The content item should contain the HTML content of the gadget. It should be thought of as a web page in its own right, so any styles, external style sheets or javascript that the gadget will require can be included within the content.
In our example function above we are setting the title to display the text "Hello World", we have set the titleicon to an empty string as we don't want to display an icon in the header. Finally we have set the content to some basic HTML and grabbed some content using standard WordPress functions (all of the WordPress functions that would be available in a plugin are also available in your gadgets).
Details on the more advanced features of the gadget display function can be found in The anatomy of a MyDashboard gadget.
Registering the gadget
So now we have our gadget coded and ready to go. The next step is to tell the MyDashboard system that it actually exists and is available for a user to add.
To do this we will add a new function underneath the "display_my_gadget" function. This new function will include the code to register our gadget.
function register_my_gadget() {
$hwoptions = array(
'id' => 'myexample_hello_world',
'title' => 'Hello World',
'createcallback' => array(&$this,'create_my_gadget'),
'editcallback' => array(&$this,'edit_my_gadget'),
'contentcallback' => array(&$this,'display_my_gadget'),
'allowmultiple' => false,
'fulltitle' => 'Hello World example',
'description' => 'An example gadget.',
'authorlink' => 'http://www.clearskys.net'
);
register_mydashboard_gadget('myexample_hello_world', $hwoptions);
}
The function above sets up a number of options for our gadget and includes the link information for our create, edit and display functions.
Once you have entered the function above, we have one final step to complete before our new gadget is ready to go.
More details on what each of the above settings are for can be found in The anatomy of a MyDashboard gadget.
Add the gadget to the MyDashboard initialisation
The last step and line of code for our gadget plugin should be placed in our plugins creator function. This ensures that the code is run when WordPress is loading all of the active plugins into memory.
Change the function called "helloworldgadget" to the following:
function helloworldgadget() {
// This is the creator function
add_action('mydashboard_gadgets_init', array(&$this, 'register_my_gadget'));
}
This adds the registration function for our gadget to the queue of functions that are called when the MyDashboard plugin is ready to start adding gadgets to the gadget library.
This completes our gadget. The full code is listed below or can be downloaded from here. Once you have the entire code saved in a file, copy it to the plugins directory of your WordPress blog and then navigate to the Plugins menu and activate it.
To check if your gadget was registered correctly, navigate to the dashboard page of your blogs administration system, and click on the "Add gadget" link at the top right hand side. Your gadget should be listed in the gadget library.
Clicking on the "Add to page" link will add your gadget to the dashboard page.
The final step, to check that all of your functions have been loaded correctly, is to click on the button to open the edit panel (in our case the little box with the V in it). This should open up the edit panel and display our "No editable options" message.
Congratulations, you have now created your first MyDashboard gadget. The next step is to get it to do something more interesting and to add some interactivity. These next steps will be covered in the next tutorial.
The completed gadget plugin
<?php
/*
Plugin Name: Hello World gadget
Plugin URI: http://dev.clearskys.net/MyDashboardGadgets/GadgetDevelopmentBasicTutorial
Description: This plugin is a basic Hello World dashboard gadget.
Version: 1.0
Author: clearskys.net
Author URI: http://blog.clearskys.net
*/
class helloworldgadget {
function helloworldgadget() {
// This is the creator function
add_action('mydashboard_gadgets_init', array(&$this, 'register_my_gadget'));
}
// the rest of the plugin code will go here
function create_my_gadget($args = false) {
// Do not want to do anything so just return true
return true;
}
function edit_my_gadget($args = false) {
// Return the information that there are no editable options.
return "No editable options.";
}
function display_my_gadget($args = false) {
$mycontent = "Hello World<br/>";
$mycontent .= "Blog title : " . get_bloginfo('name') . "<br/>";
$mycontent .= "Blog desc : " . get_bloginfo('description') . "<br/>";
$mycontent .= "Blog url : " . get_bloginfo('url') . "<br/>";
$mycontent .= "WordPress version : " . get_bloginfo('version') . "<br/>";
$mytitle = "Hello World";
$mytitleicon = "";
return array( 'title' => $mytitle,
'titleicon' => $mytitleicon,
'content' => $mycontent
);
}
function register_my_gadget() {
$hwoptions = array(
'id' => 'myexample_hello_world',
'title' => 'Hello World',
'createcallback' => array(&$this,'create_my_gadget'),
'editcallback' => array(&$this,'edit_my_gadget'),
'contentcallback' => array(&$this,'display_my_gadget'),
'allowmultiple' => false,
'fulltitle' => 'Hello World example',
'description' => 'An example gadget.',
'authorlink' => 'http://www.clearskys.net'
);
register_mydashboard_gadget('myexample_hello_world', $hwoptions);
}
}
$HWgadget =& new helloworldgadget();
?>
