Anatomy of a Gadget

Anatomy of a MyDashboard Gadget

The code for a MyDashboard gadget exists in four separate and distinct sections, each of which performs a different task during the lifespan of the Gadget.

To better explain how each of these sections of code should operate we will go through the creation, edit, display and destruction of a gadget and highlight the steps required in your code.

So, let us start our imaginary journey at the very beginning... The user has installed and activated your plugin (which contains Gadget code) and has navigated to the MyDashboard page. They click on the Add Gadgets link at the top right hand side of the page to open the Gadget Library and expect to see your gadget displayed.

To let the MyDashboard system know that your gadget actually exists, you have to provide it with some information about your gadget and then call a registration function.

Gadget registration

The first step is to gather some information together about your gadget. Some of this information is important for the MyDashboard system, so that it knows what functions to call in order to make your gadget work, and other bits are for the benefit of the user.

The information that the MyDashboard system wil accept is:

• id - This is internal identifier for your gadget. It is used throughout the system to identify your gadget (or family of gadgets). You should try to think of a unique id to avoid conflicts with other gadgets. As an example, all of the standard gadgets start with the word mydash, so the latest comments gadget has the id of mydash_latest_comments.
• title - This is the default title text displayed in the header bar of your gadget. It can be overridden in your gadgets display function.
• link - This is the default link url for the title text in the header bar of your gadget. It can be overridden in your gadgets display function.
• allowmultiple - This accepts a True or False setting and determines if the user can add more than one instance of your Gadget to their dashboard. An example of a gadget allowing multiple instances if the standard RSS Feed gadget. Think about this setting carefully as it has implications on how the rest of your gadget code needs to function.
• createcallback - This is the name of the function you have created that is called when a Gadget is added to the dashboard. There is more information on this function later in this guide.
• editcallback - This is the name of the function you have created that is called to display the Edit settings form and to handle the forms submission. There is more information on this function later in this guide.
• displaycallback - This is the name of the function you have create that handles the display of the gadget and the gadgets main functionality. It is the most important function in the development of your gadget. There is more information on this function later in this guide.

Library information

• fulltitle - This is the title of your gadget when it is displayed in the Library.
• description - This is the description of your gadget. Try to keep it to a single sentence if possible. Use the authorlink setting to direct users to further information on your own web site.
• icon - If you want to display a custom icon in the box to the left of your gadget, enter the absolute URL to it here. The icon should be a maximum of 32pixels by 32 pixels.
• authorlink - This should be the URL of a page on your website that provides further information on this gadet.
• authoremail - This is the email address of the author. It is for information purposes only, and is not currently used in the MyDashboard system.

Finally add the following line of code into the initialisation section of your plugin. This ensures that your registration function is called when MyDashboard builds the list of available gadgets.

Gadget instance creation

Once your gadget is registered, it is displayed in the gadget library on the MyDashboard page. Your gadget code will then sit dormant until the user decides to add your gadget to the dashboard itself by clicking on the "Add to page" link under your gadgets details.

This action will cause the MyDashboard system to call the instance creation function for your gadget. The function will be passed an array of information as a parameter. The array will always contain the following minimum information:

• name - This is the unqiue id that has been assigned to the added gadgets instance by the MyDashboard system. If your gadget does not allow multiple instances to be created (you set allowmultiples to false in the gadget registration) then the id will be the same as the id set when you called the registration function. If you have chosen to allow multiple instances then the id will start with your gadgets registration id, but it will be followed by a unique number (in the format _x).
• parent - This is the id of the gadget "type". In the case of gadgets that do not allow multiple instances, it will always be the same as the name (above). If you are allowing multiple instances, then it will be the id that was set when you registered the gadget (i.e. it will be the same as the value passed in name, but without the _x at the end).

It is important to remember that the name assigned to your gadget at creation time will always refer to the same instance of your gadget until it is removed from the Dashboard by the user. Once it is removed by the user, the name assigned to the instance is de-allocated and returned to the pool of available names.

It is entirely possible that a user could add an instance of your gadget to their dashboard, causing your creation function to be called, then remove the instance and add a new instance of your gadget at a later date.

Adding the instance the second time will cause your creation function to be run again and have the same name passed to it as an earlier (removed) instance. Because of this you should always overwrite any already set defaults for the name passed to the function.

An easier way to remember this: The creation function will be called ONCE and only ONCE in the life of a gadget. If the name passed to the creation function is the same as the name of a previously created gadget, then you can safely assume that the previously created gadget has been removed from the users Dashboard and you can discard the earlier gadgets data.

I hope that made sense, I might have to rewrite the chunk above.

Gadget settings update

Gadget display