Dave's Quick Search Deskbar Search Wizard

Last updated:

[ Dave's Quick Search Deskbar ]
Download version 1.3
released 21-July-2004

One of biggest pains when writing a new DQSD search is massaging the correct HTML FORM into well-formed XML.  I finally got annoyed enough to write a little utility to do some of the work for me.  I call it Dave's Quick Search Deskbar Search Wizard.

What does it do and why would I want to use it?

In a nutshell, it generates a DQSD search from the page currently displayed in your browser.

If you have no desire to ever write a search for DQSD, then don't read any further.  If you do write searches from time to time, or at least want to, then you may find the wizard useful.

The first thing I typically do when creating a new search is to view the source for the page and strip out everything but the FORM for the search.  This is tedious.  And, often it's hard to find the right FORM when there are multiple FORMs in the page.  Also, the process of converting the FORM's HTML to well-formed XML is error-prone (I always forget to close the INPUT elements with "/>").  There had to be an easier way.

OK, so how do I use it?

  1. Install the Search Wizard.
    2.   You should see a new button on your toolbar:
    If you don't, simply right-click on the IE toolbar, and click 'Customize...'.  Add the button labeled "DQSD Search Wizard" in the list of available toolbar buttons.
  2. Go to the web page containing the search you want to add to DQSD.
  3. Click in the field that contains the search string.
  4. Start up the wizard by clicking on its Internet Explorer toolbar button.
  5. You should see a dialog that looks something like the following.  Some of the fields will be automatically filled in.  Enter an abbreviation and a title for the new search.  The abbreviation is the string that will invoke the search and will be used for the file name, so keep it short and simple.

    (Hold your cursor over the different fields to see their description.)
    Enter the abbreviation for the search. This is used to invoke the search and should be a short abbreviation which isn't a common word. You also won't be able to enter uppercase or non-alphanumeric characters. Enter the title or name of the search. This is what will be displayed in the menu. Enter the URL that this search should default to if no parameters are entered for the search. The wizard will try to guess this based on the current URL, but it may not be the best default, so you should double-check it. Enter the category for this search. You can select one from the list or enter a unique category. If you don If you want to receive lavish quantities of praise for writing this search enter your name here. Or, if you feel you are not deserving of such praise because the most excellent DQSD Search Wizard did most of the work for you, then enter "Glenn Carr". If you want to be able to be contacted about this search enter your email address here. Please note that if this search ends up being distributed with DQSD, your email will be out there for everyone to see, which isn't necessarily bad, but I like to enter my email in the form 'glenn at glenncarr dot com' just to keep bot email harvesters from finding it. Enter switches, if any, that you want to use with this search. Script will be generated for parsing the switches if you do enter some. Do you want to include examples in the description? If so, check this box and some placeholders with the standard formatting will be inserted in the description. Enter a helpful description for this search. It can be as long or as short as you prefer. OK, so what this really means is... "Does it make sense for this search to get only one switch at a time (i.e., they are mutually exclusive), or does it use a combination of switches?" The switch parsing code which is generated will be a little different depending on your choice here. Do you want to include the switches in the description? I don't really see why you wouldn't want to, but if so uncheck this box. This is a list of the form elements on the current web page. Check the box next to the form(s) which are required for your search. If you selected, or made active, an input field before you started up this wizard, its form should be checked below. If you select or highlight a form, an attempt will be made to make it visually standout according to the CSS styles (check the options). This can be helpful if you aren't quite sure which form to include in your search. This button will hide or display the HTML for the selected form. This was simply provided as another aid in determining the correct form(s) to include in your search. Change various options. Check out who wrote this wizard and recent changes. Show help in the form of tool tips.
  6. In the list of FORM elements, make sure at least one FORM is checked.  If you clicked in a field before invoking the wizard, the FORM containing that field should be already be checked.  Selecting a FORM in the list and expanding the dialog by clicking the HTML button will show the HTML content of the FORM.  Selecting a FORM will also change the background and outline of the FORM on the web page in most cases.  This is really just to provide some help in determining which FORM(s) you need include.  You can check multiple FORMs, all of which will be included in the search file.
  7. Hit OK and you'll be prompted to save the search file to your DQSD 'searches' directory.
  8. After saving the file, it will come up in Notepad by default.  (Click 'Options...' to change the editor to something other than Notepad.)

Example

In the screenshot above, I went to http://www.loc.gov (the US Library of Congress) and clicked in the search field...

Then I clicked the 'DQSD Search Wizard' button.  All FORM elements in the page are listed (in this case only one), with the one checked that contains the 'active' element.  I entered an abbreviation and a title (the title appears in the menu and help).  Finally, I pressed 'OK' and I was prompted to save 'loc.xml' to the 'searches' subdirectory of my DQSD installation.

The resulting XML file search file will look something like the following.  And, in spite of the comment at the top of the file, this search just works.  Woo hoo!  (Well, I find it fairly exciting.)  Granted, complicated searches won't 'just work', but the wizard will at least do a bunch of the tedious work for you.

<search function="loc"> <COMMENT> Even though this XML search will probably load and is a good start toward a completed search, please be aware that this search will probably not work as is and will probably require some changes. </COMMENT> <name>Library of Congress</name> <category>Reference</category> <contributor>Glenn Carr</contributor> <link>http://www.loc.gov/</link> <email>glenn at glenncarr dot com</email> <description> Search the Library of Congress <div class="helpboxDescLabels">Examples:</div> <table class="helpboxDescTable"> <tr><td></td></tr> <tr><td></td></tr> </table> </description> <form name="locf" method="get" action="http://search.loc.gov:8765/query.html"> <COMMENT> The following field was active (i.e. had focus) when the search was generated. </COMMENT> <input type="hidden" name="qt" value="" /> </form> <script><![CDATA[ function loc(q) { if( nullArgs("loc", q) ) return; // FORM variables for locf // The wizard assigned the search string to this form field value because // this field was the active element when the search file was generated. // Change this to args.q if the search string is parsed with parseArgs. document.locf.qt.value = q; submitForm(locf); } ]]></script> <copyright> The following applies if this file is included and distributed with Dave's Quick Search Deskbar: Copyright (c) 2002 David Bau; Distributed under the terms of the GNU Public License, Version 2 (http://www.gnu.org/copyleft/gpl.txt) </copyright> <created_by> This search file was initially created on 10/23/02 at 09:42:52 by Dave's Quick Search Deskbar Search Wizard version 1.0.0 , Copyright (c) 2002 Glenn Carr; Distributed under the terms of the GNU General Public License, Version 2 </created_by> </search>

Switches

The 'parseArgs' utility method has become the convention for parsing switches for searches.  If you enter some switches in the 'Switches:' field of the search wizard...


...the generated search will now include basic code for parsing the switches:

// Parse switches with parseArgs: // parseArgs usage: // Arguments: // q - string from the search function // expectedSwitches - list or array of the expected switch values // expandSwitches - optional parameter [default = true] used to determine // if the switch shortcuts should be expanded (i.e. /f becomes /foo) // Returns an object with these properties: // q - the input string with the switches removed // switches - array of objects with these two properties: // name: expanded name of the matched switch (i.e. foo as in /foo:bar) // value: value of switch (i.e. bar as in /foo:bar) // switch_val - associative array with the switch name as the key with the switch value // as the value. (i.e. switch_val["foo"] = "bar" as in /foo:bar) //var args = parseArgs(q, "news, sports, business"); //if ( args.switches.length > 0 ) //{ // switch( args.switches[0].name ) // { // case "news": // break; // case "sports": // break; // case "business": // break; // default: // break; // } //end-switch //}

Anyway, that's the gist of it.  It still needs a lot of testing, and there is plenty of room for improvement.  It's also open source like DQSD, so feel free to hack away and send in bug fixes.


October 23, 2002

Credits