GUI Deployment Descriptor (GUIDD)

Standard Specification and Documentation

Revision 0.99.5, 10.05.2006
Maintained by Josef Spillner <js177634@inf.tu-dresden.de>

Table of Contents

1. Introduction
2. The GUI Deployment Descriptor (GUIDD)
3. Dialogs
4. GUI Elements
5. Returning the Output
6. Internationalisation
Appendix A: Formal GUIDD Definition
Appendix B: Usage scenarios
Appendix C: Acknowledgements and Revisions

1. Introduction

Web services are standardised by discovering them via directories like UDDI, reading their structure via service description files like WSDL and communicating with them via XML messaging protocols like SOAP. Their introduction is intended to facilitate the information workflow between applications.

Navigating a web service as a user is hard to impossible: More often than not, internal variable names are used, along with complex type definitions, value restrictions and unclear services and operations.

The WSGUI concepts allow a GUI Deployment Descriptor (GUIDD) to be placed side by side with a WSDL file to make the internal operations visually accessible to the user, independent of the environment like desktop toolkit or web browser. As it is likely that other bridges between the user interface and the underlying services might exist, the differentiation between the terms GUIDD and WSGUI should be understood.

2. The GUI Deployment Descriptor (GUIDD)

A GUIDD file is an XML-formatted file and consists of a header and 4 sections. The header is a standard XML 1.0 header, and the sections are contained within the document (root) element, named deployment. The corresponding WSDL or other web service description file is specified as well in the header part within the source tag.

<?xml version="1.0" encoding="UTF-8"?>
<guidd:deployment xmlns:guidd="http://wsgui.berlios.de/namespaces/guidd">
<guidd:source href="...">
   ...
</guidd:deployment>

For convenience reasons, the guidd: namespace is from now on omitted in this specification, however it should be used when building such documents. The namespace URI is http://wsgui.berlios.de/namespaces/guidd.

Of the 4 sections, one describes the general page creation, namely operations. It is coupled to the existance of a web service file, just like source is. Another two are responsible for the display of input and output forms. They are formComponents andand outputTypes, and can be used with any XML Schema. Finally, the section titled stylesheets can optionally specify a CSS stylesheet which is used for GUIDD in a web context.

<operations>
   <operation>...</operation>
   ...
</operations>
<formComponents>
   <formComponent>...</formComponent>
   ...
</formComponents>
<outputTypes>
   <outputTypes>...</outputTypes>
   ...
</outputTypes>
<stylesheets>
   <stylesheet>...</stylesheet>
   ...
</stylesheets>

Each of those 4 sections consists of child tags named just like the parent tag, but in the singular form. They will be explained in detail in the next paragraphs. In essence, the GUIDD format implements the WSGUI concepts of form components, service descriptions and MIME awareness.

3. Dialogs

Depending on the level of web service integration, displaying a dialog for navigation can start at basically 4 points: At the web service selection (outside the scope of WSDL or GUIDD), at the service selection (only in case more than one is provided), at the operation selection or at the final point, the input dialog for a pre-selected operation.

GUIDD supports the steps 2-4 with additional information, beside building up the input and result output dialogs which will be covered in the next section.

Each operation comes with extended information, using the prettyName and description tags and the name attribute to associate the operation hints with the WSDL operation. In addition to this, a submit button caption can be given, containing an XForms submit element.

<operations>
   <operation name="...">
      <prettyName>...</prettyName>
      <description>...</description>
      <submit>
      <xf:submit>
         <xf:label>...</xf:label>
      </xf:submit>
      </submit>
   </operation>
   ...
</operations>

GUIDD also supports step 5, the output dialog, which is modelled just like the input dialog, except that instead of input fields, there are text and media fields for the output. In terms of XForms, output format-specific form components are used for the output, since XForms is not MIME aware.

4. GUI Elements

Both web forms and rich-client GUIs allow for many standard and custom widgets and form elements to be used in dialogs. For GUIDD however, it suffices to concentrate on a selection of them, as long as they support all required properties. These elements are taken from the XForms standard to allow for reusable GUI definitions. For applications which do not provide XForms support, transformers exist to generate HTML pages or other legacy formats.

In all the GUI elements which present particular strings to the user (as do label and help), multiple such tags can occur as long as they are distinguishable by means of their lang attribute, which specifies texts for different languages. This is an extension to XForms. See also the chapter about Internationalisation.

Each GUI element is contained in a formComponent tag, which provides an XPath locator (xpath) to find out which elements in the schema to apply to, or in case no XPath support is available, a simple matching can be done using the element attribute which corresponds to a WSDL element. In addition, an ixpath attribute can specify an instance path, which always overrides the schema xpath and locates an element of the instance.

<formComponents>
   <formComponent xpath="..." ixpath="..." element="...">
      <xf:input>
         <xf:label>...</xf:label>
         <xf:label lang="...">...</xf:label>
      </xf:input>
   </formComponent>
   ...
</formComponents>

5. Returning the Output

The XForms standard does not cover the output of results, which are important elements in GUIDD, as the result forms are very similar to input forms in the request-response model. In order to make the output more useful, some GUIDD tags are available.

One such tage would be that whenever a binary stream (base64 or hex encoded) is returned as part of the result, a MIME type is associated with it so that the output for images, sounds or similar data can happen as a user would expect, instead of just looking at the raw data stream. While some implementations might prefer an auto-detection, as is the case for images of varying formats, it still helps to improve the user experience.

<outputTypes>
   <outputType xpath="..." ixpath="..." element="...">
      <mimetype>...</mimetype>
   </outputType>
   ...
</outputTypes>

Appendix A: Formal GUIDD Definition

For a formal definition of the file format of GUIDD documents, please refer to the file guidd.xsd which is written in XSD (XML Schema Definition) format. This file always corresponds to this specification, while older versions can be found along with it in the archive section of the site.

Location: guidd.xsd

The GUIDD format employs elements of the XForms 1.0 standard.

Location: http://www.w3.org/TR/xforms/

The GUIDD format is mapped on top of web service description languages such as WSDL or OpenSearch, although none of these is particularly required for GUIDD to be useful.

Locations: http://www.w3.org/TR/wsdl/, and http://opensearch.a9.com/spec/opensearchdescription/1.0/

The GUIDD concept tries to keep the dependency standards to a minimum to allow for flexible usage in various scenarios. The following appendix does however list a couple of possible uses.

Appendix B: Usage scenarios

GUIDD can be used on web pages, especially in portlets or servlets, to improve the integration of web services with those environments.

The construction of application-platform GUIs like XUL or XAML can benefit from using GUIDD mappings to the respective internationalisation methods.

Finally, native desktop GUIs can integrate dynamic dialog generation methods with WSGUI, and GUIDD is the key to keeping their renowned usability and integration on a high level. Examples include the Qt XML GUI and the various standards for the Java Swing platform.

Appendix C: Acknowledgements and Revisions

The WSGUI concept project is maintained by a potential collaborative effort, which is hosted at http://wsgui.berlios.de/. The GUIDD specification master location is http://www.inf.tu-dresden.de/~js177634/webservices/guidd.html. The efforts are coordinated by:

• Josef Spillner (e-mail), TU Dresden

WSGUI/GUIDD was founded as part of the FX-Agents research project at Stanford University. The initial work is thus credited to:

• Michael Kassoff
• Daishi Kato
• Waqar Mohsin

Their work comprised both generic and web-specific GUI explanations. This specification does not cover the web-specific parts, but leaves them to another document which will also be released by the WSGUI concept project, to take into account the changes in related web standards.

Revision 0.99.5 (10.05.2006):
In line with current WSGUI research, the GUIDD format has been cut down and clarified to only contain the necessary and already implemented sections. Therefore, dynamic enumerations and pages have been removed. The coupling with WSDL has been weakened by introducing non-WSDL terms in the syntax. The ixpath locator has been introduced for formComponents and outputTypes.
Revision 0.99.4 (05.01.2006):
Put specification into perspective of the newly launched WSGUI concept project.
Revision 0.99.3 (19.08.2005):
Effect of internationalisation and usage of the lang tag. Extended inclusion of related standards.
Revision 0.99.2 (01.07.2005):
Many cleanups and adaptation to existing efforts. Better description of the general layout of a GUIDD file. Removal of the specific XForms documentation. Introduction of the outputComponent tag.
Revision 0.99.1 (08.06.2005):
Mention of XForms form element borrowing, and start of chapter for output.
Revision 0.99.0 (06.06.2005):
Initial revision. First comprehensive overview about WSGUI. Introduction of multiline input fields, feature enablers and a general i18n strategy.