The Clip Notes Widget
Clip Notes is a widget that uploads notes to to web servers. Users can drag an image file, highlighted text, or URL into the widget (Figure 1), or type text into the widget. When users press the Upload button, the contents of the widget gets uploaded to a web server, which has a simple PHP application to save the uploaded note to a database. For viewing, there's another PHP script that reads the notes from the database, and displays them to users; see Figure 2.
Widgets typically use images as the basis for visual components, rather than programmatic approaches available in Java, Ruby, or Python. This example uses images for the widget background and Upload button.
The main specification for the Clip Notes widget is maintained in ClipNotes.kon (Listing Two). This is an XML file responsible for establishing the widget's look-and-feel. Line 1 contains a processing instruction that tells the XML processor it's dealing with an XML file. Line 2 is a processing instruction specifying that a strict interpretation of XML should be used when parsing widgets. Similar to HTML, the widget parser doesn't require a widget to conform to all aspects of the XML specification by default. For example, you can specify an attribute value that isn't surrounded by quotes. This can cause problems if the widget must be parsed as an XML file, so it's generally better to set this flag to True.
The widget element primarily consists of the window specification (lines 4-24), two actions, and some preference information. Looking into the window specification in line 4 shows the basic attributes of the widget's window (the height/width are defined), and a set of child elements that establish the content of the widget. A few basic elements create the look-and-feel of a window. Images, text fields, and text areas are the most common elements, and each specification is positioned in the container window using horizontal/vertical offset attributes.
Turning to the actions defined after the window, the trigger attribute of each action indicates when it is executed. With the action element defined in lines 25-31, you can see that it is similar to a standard JavaScript event handler. The onload trigger causes the action to be executed when the widget is loaded, and the content of the action element is embedded JavaScript code. It is important to note that the JavaScript is defined in a CDATA section with <![CDATA[ ... ]]>. This ensures that the Widget Engine doesn't misinterpret any special characters like greater than (>) or less than (<) symbols in the script when parsing the widget file. It should be used for all JavaScript embedded in the .kon file.
The CDATA section of the embedded JavaScript reveals two interesting aspects of a widget. First on line 27, the include statement loads an external JavaScript file. This lets you keep the JavaScript and the XML specification separate. In this case, we include a single file, ClipNotes.js, that contains all the JavaScript functions. The log function in line 28 is a JavaScript extension provided by the Widget Engine and aids with widget debugging. When the widget's debug attribute is set to True, a console that captures log messages is loaded with the widget.
The final step in the onload script (line 29) calls the updateFromPreferences function in the external JavaScript file to load saved user preferences. This function is also called by the action defined on lines 32-36 which is triggered by an onPreferencesChanged event that fires when users change a preference value.
It is also possible to associate JavaScript outside of action elements. Windows and other visual components can associate a script with an event like a key press or standard mouse events. You can define child elements of the component that describes the event to capture, and the function, or embedded JavaScript, to execute when the event fires. The Clip Notes widget associates external JavaScript functions with key presses, and drag-and-drop events in the dropBox text area on lines 12-13, and captures when users press and release the Upload button on lines 21-22.
The JavaScript Specification
The JavaScript specification file ClipNotes.js contains all the functions for handling events—functions to handle user preferences, enable file drag-and-drop, and upload the note or image to servers.
