This is the first part of a new blog series that will describe, in detail, all major aspects of the widget framework available in Windows Mobile 6.5.
The widget manifest is an XML file that describes the corresponding widget in detail so that Windows Mobile can actually do something with it. This is the first file we look at when the widget is being installed or executed so, even though it is simple, it is extremely important.
For Windows Mobile 6.5 we implemented widgets based on the W3C Widgets 1.0: Packaging and Configuration standard dated Dec-22-08. While the standard continues to evolve, our implementation remains backwards compatible with very few exceptions – notable exceptions will be called out in this blog series. To save you some W3C reading time, in summary, the widget manifest has to be called config.xml and its presence is required in order for the widget to be considered valid. Technically you could provide an empty widget manifest and thus get something installed, since all elements inside config.xml are optional. That said, I recommend that at the very least you define the elements that are present in the following example:
<?xml version="1.0" encoding="utf-8" ?>
<widget xmlns="http://www.w3.org/ns/widgets"
version="1.0"
id="http://someSite.com/MyUniqueWidgetID">
<name>My first widget</name>
<content src="widget.htm" type="text/html" />
<access network="true" />
<icon src="icon.png"/>
<icon src="icon.ico"/>
<description>
This is my first widget,
it won't make a lot of money on the
marketplace but at least is cute!
</description>
<author href="http://www.windowsphone.com/blog"
email="jorgeperaza@hotmail.com">Jorge Peraza</author>
<license>
Example license (based on MIT License)
Copyright (c) 2008 The Foo Bar Corp.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
INSULT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
</license>
</widget>
The Widget Element: What Makes Me… Me?
The first element I would like to cover in detail is the <widget> element, the father of all other widget configuration elements.The document can have only one and, from the many attributes that can be specified, we only honor the following two in the current release:
- version="1.0" This attribute specifies the widget version number, we use this to check if, when trying to install a new widget with the same id it should be allowed as an upgrade or not.
- id ="http://someSite.com/MyUniqueWidgetID" This attribute is actually extremely important, this is the unique per widget ID that the framework uses to identify installed widgets.This has to be a well-formed URI but it does not have to be valid.
Some of the child elements like <name>, <description>, <author> and <license> are self-explanatory so I won’t bore you with details for them. See? I’m nice sometimes :-).
Now, let’s talk about one of the most important child elements which happens to be <content src="widget.htm" type="text/html" />This element tells the widget framework which source file to load to execute the widget.You might also notice that the MIME type is also specified here… however on WM 6.5 we only support "text/html" so don’t get any ideas!!
The next group of interesting child elements are the set of <icon src="icon.png"/> which allow you to specify one or more icons for your widget. Icons are very important because they give your widget their unique personality. Now, there are some important limitations widget writes should be aware of. Windows Mobile Professional (touch screen) supports both PNGs and JPGs as image file formats to be used as widget icons, however, Windows Mobile Standard only supports ICOs (Please, don’t ask :-)) Soooo, in order for your widget to show best on both platforms I recommend having both and listing the PNG or JPG first.
Last but not least let’s talk about <access network="true" />. This is an optional element that is required to be “true” if your widget accesses network resources, otherwise you can leave it out (but all cellular network calls will fail).
I went to all the effort for defining all fields in the manifest… can I at least access them from my widget?
Glad you asked, and the answer is… of course! You can do this by using the widget metadata API available to you courtesy of the “widget” javascript object. Below are the relevant properties that you can use to get information out of the manifest:
- widget.version
- widget.identifier
- widget.name
- widget.description
- widget.authorEmail
- widget.authorName
- widget.authorURL
- widget.height
- widget.width
- widget.locale
That’s it for now. Please stay tuned for more information and happy widget writing!