Monday, December 25, 2006

Creating a Widget Installer

Several readers asked me to write a tutorial on how to make a one-click widget installer, like the one I made for installing the Recent Posts Widget. Well, that seemed a good idea, so here it is. The purpose is to make you understand how it works, so that you can create your own. Disclaimer: Brainless copy-paste won't work.

Step 1: Create a Widget
If you want to create a Widget Installer, obviously the first thing you need to do is to create the widget itself. A real one-click-installable widget should contain all the necessary code. So if there is javascript-code that need to be installed, try to embed it inside the widget.
Just for the fun of it, let's create a Random Quote Widget (thanks Annie).
Open your Blog's template, add a HTML/Javascript page-element, set the title to "Random Quote", and add the following javascript to its content:

<script language="JavaScript">
//store the quotations in arrays
quotes = new Array(6);
quotes[0] = "So many cats, so few recipes.";
quotes[1] = "Use the best: Linux for servers, Mac for graphics, Windows for Solitaire.";
quotes[2] = "That's not a haircut. That's a cry for help.";
quotes[3] = "The last thing I want to do is hurt you. But it's still on the list.";
quotes[4] = "Some days it's just not worth gnawing through the leather straps.";
quotes[5] = "Doing for blogging what Ghengis Khan did for social work.";
//calculate a random index
index = Math.floor(Math.random() * quotes.length);
//display the quotation
document.write("\n");
document.write(quotes[index]);
//done
</script>

This code is a javascript script. What it does is easy to understand. It creates a data structure called an array, with six elements. The elements are number 0 through 5. Then it calculates a random number from 0 to 5, and displays the array-element with this index. This is just plain javascript.
Save the widget, and see how it works. Every time you reload your page, a new quote will appear.

Step 2: Understand how widgets can be added to Blogger
Now that you have created your widget, you have to learn how you can add a widget to Blogger. That is explained in the Blogger Help pages. What you have to do is that you have to create a FORM. A form is a HTML-element, and can have input boxes, radio-buttons, check-boxes, buttons, and so on.

Step 3: Create a Widget Install Button
Now we will create our own Install Button using a form. Our form has to look like this:

<form method="post" action="http://beta.blogger.com/add-widget">
  <input name="widget.title" style="display:none" value="Random Quote"/>
  <textarea name="widget.content" style="display:none;">
     &lt;script language="JavaScript"&gt;
       //store the quotations in arrays
       quotes = new Array(6);
       quotes[0] = "So many cats, so few recipes.";
       quotes[1] = "Use the best: Linux for servers, Mac for graphics, Windows for Solitaire.";
       quotes[2] = "That's not a haircut. That's a cry for help.";
       quotes[3] = "The last thing I want to do is hurt you. But it's still on the list.";
       quotes[4] = "Some days it's just not worth gnawing through the leather straps.";
       quotes[5] = "Doing for blogging what Ghengis Khan did for social work.";
       //calculate a random index
       index = Math.floor(Math.random() * quotes.length);
       //display the quotation
       document.write("\n");
       document.write(quotes[index]);
       //done
       &lt;/script&gt;
    </textarea>
   <input type="submit" name="go" value="Add widget to your blog"/>
</form>

Let us take a closer look at this form. As usual with HTML, there is an opening-tag <form> and a closing-tag </form>. The content of the form has to be posted to the url http://beta.blogger.com/add-widget. This information is added to the form opening tag. The form has to contain 3 elements: the widget title, the widget content, and a button to submit the form to Blogger. The widget title is set using an Input Field in the form. The name of this input field has to be set to "widget.title", so that Blogger knows it is the widget title. The value of this field can be anything you like. The value is displayed on your Blog as the widget's title. In this example I set it to "Random Quote", but it could also be "A Very Deep Thought".

The widget content is the javascript-code from step 1. We put this javascript inside a textarea-field. The textarea has an opening tag and a closing tag. Put the javascript between these two tags. Inside this form, we have to make sure that the javascript is handled as text, and not as javascript. Therefore, replace all < with &lt; and replace all > with &gt;. The name of the textarea is set to "widget.content" so that Blogger knows that this field contains the widget content. The style of both the title input and the textarea is set to display:none, so that the user doesn't see them (but don't worry, it is there all the same).

Finally, there is an input button, the value is displayed as the button text.
If you copy this form and paste it to the end of the widget-code that is already in your sidebar, you will get a button below the widget, and clicking the button will install the widget to your visitor's blog.