How To Add A Google Box To Your Weblog

That Google? Yup.

You may ask, what is a Google Box ... not to mention, why should I care? Don't worry. I have anticipated all:

That is a Google Box. Once you learn the very simple magic involved in getting one of these into your weblog, you can substitute your own Google query text for mine. The one I used in the box above was ... "Google".

Radio sent that query across the Internet wires to the 'real' Google search engine. Google did exactly what it does if you had typed that search query yourself at the Google home page. Google then sends back to Radio the first ten search results and Radio displays them in the ... Google Box.

You'll notice that querying Google about Google, besides being a bit weird, didn't turn up a whole heck of a lot of interesting results. There is an art as well as a science to working with search engines. Happily, it is easy to change your query and redisplay your Google Box with the new query.

Anyway (and this is a big 'anyway'), can't we just have some fun with our weblogs? If I want to use my Google Box to insert some whimsical queries into my weblog, do I need to ask anyone's permission? Must everything have a cosmic purpose? What happened to blinking text and page counters is what I want to know. On second thought, thank goodness they went away ...

Seriously, Google Boxes are the leading edge of some fascinating programming and content management experiments that may yield exciting new features galore for end users like you and me over the coming years. Putting a Google Box into your weblog is just a way that end-users can join the fun.

Are you ready?

(This topic is a syntactically sugary version of Dave Winer's Google Box recipe. Use his recipe, mine or both as you see fit).

Dancing With Google

Understandably, the folks at Google expect us to establish a (free) user account with them in return for their neighborliness to us. Here is what you need to do:

1. Go to this URL at Google to create your account from a screen that will look like this:

Pretty darn simple. Enter a real email address so they can send you the needed 'key' code to activate your account. Enter and repeat your password. Click in the box to accept their terms - they are staightforward so don't sweat it.

2. Google will send you an email reply with a link to a page on their site where you can verify your identity.

(Note: you should access that account page fairly quickly since the link they give expires after a short period of time. Most likely, you will receive your key by email within a few seconds or minutes after you complete step one ... so try to sign-up within one working session. Going out to dinner won't work).

3. Google will activate your account almost immediately after you complete step 2 above. Google will send you another email verifying your sign-up. It will contain a text version of your Google key. Keep this email so you can enter your key in the future should this be requested.

Wire Google To the Radio Desktop Application

1. Update Radio.root (right-click the Radio icon in your Windows status bar and select 'Update Radio').

Most likely, your version is already updated to support a Google Box but it never hurts to make sure. See How To Update Radio for more help.

2. Right-click the Radio icon again and select 'Open Radio'. See How To Open the Radio Desktop Application if this confuses you.

3. Choose QuickScript from the Developers submenu of the Tools menu as shown below:

4. Enter google.init() exactly as shown and click 'Run'. This will display 'true' in the dialog window:

This means Radio acknowledges the Google connection code in your copy of Radio and will be ready to interact with Google.

5. Choose Jump from the Developers submenu of the Tools menu as shown below:

6. Enter user.google into the Jump box and click OK:

7.  Open or click back to the email application that contains your Google key. Select the key by dragging your mouse across the key text and choose 'Copy' from the File menu of your email program.

Then, return to the Radio desktop application and put your cursor into the 'Value' field of the dialog box shown below. Choose Paste from Radio's own Edit menu. This should place the Google key text into the Value field.

Simply close this dialog box by clicking the 'X' button at the upper right part of the window. Don't worry. Radio will automatically save your key.

(Understandably, I have 'emptied' my key number from the screen capture above ...).

8. You may now close the Radio desktop application by choosing 'Exit' from the File menu. 

You have now wired Google and Radio together.

Placing the Google Macro Into Your Weblog

Now, for the fun part.

1. Open your local Radio weblog home page if it is not already open. If Radio is already open (it has to be if you have just finished the instructions above), right-click the Radio Icon in your Windows status bar and choose 'Home Page'. This will load your local weblog home page.

2. Select the Prefs section link from the Radio Command Menu. That command menu is displayed on every page of your local Radio weblog.

3. In the Prefs section, choose the 'Home page template' from the Templates section:

4. Enter the Google macro text just under the navigatorLinks macro in your own Home Page Template. See What Is A Macro if you would like a simple explanation of this concept.

Consult the relevant portion of my template below as a guide:

Note the following ...

... Your template text will probably look different than mine but every home page template has a navigator links macro - <%navigatorLinks%>. Take your time looking through the weird codes until you find it. It is there.

... Enter the Google macro text exactly as you see mine: <%google.macros.box ("Google")%>. However, feel free to change the 'Google' inside the parentheses to another search query. In other words, the text you enter between the quotation marks is the text that Radio sends to Google as the basis for the search. Don't forget that your own search text must have double quotation marks around it! Computers are very petty.

5. Click 'Submit' to confirm the changes to your Home Page Template.

6. If upstreaming is on, fine. Otherwise, turn upstreaming on so Radio will publish your Google Box to your public site. By the way, you won't see the Google Box on the home page of your local weblog where your text entry box appears ... so don't be dismayed that it isn't there.

Also, give Radio a bit of time to upstream the template change. You can take a look at the Events page to assure yourself that the change has been published. That is accessible from the Radio Command Menu.

If Murphy has not intervened, you can now go to the upstreamed, public version of your weblog and your Google Box will be staring proudly back at you.

If something has gone wrong, it will probably be because there is a typo in your Home Page Template. Go back there and take a very slow, very long and very careful look at what you entered there.

Good luck!

For Extra Credit: Other Parameters For Your Google Box Macro Text

By default, your Google Box will display the top-ten results for your search query. You cannot display more than ten but you can display less then ten. Do this by ...

1. Returning to your Home Page template.

2. Replacing the current value within the parentheses of your Google macro with something like this: <%google.macros.box ("Google",5)%>.

3. Make sure upstreaming is 'on' and choose 'Submit' to confirm the changes to your Home Page template. You should now see five results to your query on the home page rather than ten.

Note: the search query (in this case, "Google") must appear within the parentheses. The parameter (5) follows a comma. Picky, picky, picky.

If you are feeling brave, go back now and take a close look at Dave Winer's recipe. He includes a list of all possible parameters for your Google Box at the bottom of his document.

Changing Your Google Box Search Query

You can change your Google search query anytime by returning to your Home Page template and ... changing the text. For instance ...

<%google.macros.box ("Userland")%> will search Google for results pertaining to Userland.

As always, be careful to enter the query precisely and retain the quote marks. Submit the Home Page template change and make sure upstreaming is turned on.

Where Can I Place My Google Box?

You don't have to put your Google Box exactly where I put mine. You can put the Google Box macro elsewhere in the Home Page template. Experiment.

If you want to be safe, make a backup copy of your important Radio files so you can copy your original home page template text back to your weblog if disaster strikes ... however unlikely.

You can place additional Google Boxes in your Main Template or even within a weblog post. To be more precise, you can place the Google macro text - with a different search query text - into the Main Template.

I won't pause here to document these variations in detail. If specific issues arise, email me and I will address them in a later revision of this topic. Maybe.

Bottom line? Who needs a Google Box? No one. But then, who needs hot fudge sundaes either?

Me.

 <-- Return to Home Page