XHTML support in the Welcome Framework.

Summary
This document describes the new XHTML 1.0 support in the Eclipse 3.1 Welcome framework. This new feature is still evolving, and feedback is welcomed.

Last modified: Feb 17, 2005

 

Background

In Eclipse SDK 3.0, a new welcome framework was introduced to replace the existing editor-based welcome framework. It allowed for authoring Welcome pages using custom Intro XML markup. This kept content completely separate from presentation, which in turn was solely controlled by CSS or .properties files. A custom markup language was introduced to allow for the dynamic contribution to a given welcome page. This pluggable architecture for a given welcome page was needed to follow the same dynamic plugin nature of the platform itself. That is, a page can:

• include content from other welcome pages.
• contribute content to another welcome pages.
• have content programmatically injected into it. (This content is typically the result of some query to the workbench through java code. An interface in the intro framework allows for dynamically interacting with the generated HTML page and populating the html page with more content, on the fly. For example, a welcome page can dynamically create and display a list of projects in the workbench.)

These features where implemented in 3.0 using a custom intro XML markup, and while the design satisfied the requirement, feedback pointed to the need for easier authoring. One such usability enhancement is to allow Welcome pages to be created by WYSIWYG editors, eliminating the need for the visual designer to know any details about the internals of the Intro framework. Once created, these pages can then be contributed as Welcome pages and assembled together into one coherent "out of the box" experience.

Proposed Solution

Intro content will now be contributed with XHTML 1.0 documents (A reformulation of the three HTML 4 document types as applications of XML 1.0. For M5, only XHTML 1.0 is supported. XHTML 1.1 (module-based XHTML) can be supported, based on feedback.). The idea is to use the fact that XHTML is well formed XML and parse each document, manipulating the DOM to allow for contributions and extensions to be merged. Three xml elements from the 3.0 intro markup where used to extend the XHTML 1.0 element list. These where include, anchor, and contentProvider.

•  include: this element can be added to a valid XHTML document to include content from another XHTML document. The content to be included must be a valid XHTML snippet.

e.g.: <include path="root/foo" /> will include an element with id foo from a welcome page with id root.

•  anchor: this element can be added to a valid XHTML document to declare that content can be contributed to this page by other welcome contributions. A page declares locations that are suitable to be extended by defining these anchor points.

e.g.: <anchor id="anchor1" /> will allow for contribution into this page from other plugins.

• contentProvider: this element can be added to a valid XHTML document to establish a hook into the workbench. When the intro framework encounters this element, an interface is called allowing for the manipulation of the DOM of the XHTML page.   

e.g.: <contentProvider id="contentProviderId" class="org.eclipse.ui.intro.template2.IntroXHTMLContentProvider" pluginId="org.eclipse.ui.intro.template2"> </contentProvider>
 will allow for dynamic content to be generated from the org.eclipse.ui.intro.template2.IntroXHTMLContentProvider class.

With these three elements, XHTML pages can be used to assemble a pluggable and dynamic welcome experience.

Note: if the only requirement is to render a tree of HTML documents (from the file system or from the net), with no need for extensibility, then this is already supported in Eclipse 3.0. A page can simply be defined as follows:
    <introContent>
        <page id="homePageId" url="http://eclipse.org"/>
        <page id="standbyPageId" url="./static001/standby.html"/>
    </introContent>

The html page is loaded from the specified url, and displayed in the Welcome view as is. In this scenario, the html page can make use of the custom intro url actions. The browser in the welcome "knows" how to interpret these urls in a special way, allowing for interaction with the workbench from a static html page.

Hello World Sample

Here are the steps to create a Hello World XHTML Welcome page : 

• contribute a product :

<extension id="product"1 (italic means a user specified value) point="org.eclipse.core.runtime.products"> 
    <product name="%example.product.name" 
        application="org.eclipse.ui.ide.workbench"> 
    </product> 
</extension>

• contribute an intro part and bind it to the product you just created :

<extension point="org.eclipse.ui.intro"> 
    <intro
        class="org.eclipse.ui.intro.config.CustomizableIntroPart"
        id="org.eclipse.ui.intro.template2.introId"> 
    </intro>
    <introProductBinding
        introId="org.eclipse.ui.intro.template2.introId"
        productId="org.eclipse.ui.intro.template2.product">
    </introProductBinding>
</extension> 

• contribute a config (configuration) to the intro part you just created :

<extension point="org.eclipse.ui.intro.config"> 
    <config id = "template2_configId" 
        introId="org.eclipse.ui.intro.template2.introId" 
        content="introContent.xml">
    <presentation home-page-id="root">
        <implementation kind="html"/>
    </presentation> 
    </config> 
</extension> 

• create an intro content file, introContent.xml, that describes all your pages, and that you referenced in your intro configuration :

<?xml version="1.0" encoding="utf-8" ?>
<introContent>
    <page id="root" content="content/root.xhtml"/>
    <page id="concept1" content="content/concept1.xhtml"/>
    <page id="concept2" content="content/concept2.xhtml"/>
</introContent>

• create the actual XHTML pages referenced by the content file. Here is root.xhtml : 

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>root.xhtml</title>
    <link rel="stylesheet" href="root.css" type="text/css" />
</head>
<body>
    <h1>Welcome to Product A</h1>
    <h4 id="firstH4">
        <img border="0" src="welcome_item.gif" alt="Concept1" />
        <a href="http://org.eclipse.ui.intro/showPage?id=concept1">Learn about Concept One... 
        </a>
     </h4>
    <h4>
        <img border="0" src="welcome_item.gif" alt="Concept2" />
        <a href="http://org.eclipse.ui.intro/showPage?id=concept2">Learn about Concept Two...</a>
    </h4>
    <anchor id="anchor1" />
</body>
</html>

• launch a runtime-workbench with the product id you just created to see the simple intro :

Extending the Hello World Sample

Here are the steps to contribute to the above Hello World intro sample : 

• contribute a configExtension declaring that you want to extend the original configuration :

<extension point="org.eclipse.ui.intro.configExtension">
    <configExtension configId="template2_configId" 
        content="ext.xml"/>
</extension> 

• create the extension content file and declare what the extension content is. extensionContent element specifies the location of the content file and the target path where this extension content needs to be inserted. If this new content needs to reference other pages, these pages can be declared in the same extension content file, as below : 

<?xml version="1.0" encoding="utf-8" ?>
<introContent>
    <extensionContent content="content/extContent.xhtml" path="root/anchor1" />
    <page id="concept3" content="content/concept3.xhtml"/>
</introContent>

• create the actual extension content, and save it as a separate file, extContent.xml :

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
	<title>root.xhtml</title>
	<link rel="stylesheet" href="root.css" type="text/css" />
</head>
<body>
	<h4>
	  <img border="0" src="welcome_item.gif" alt="Concept2" />
	  <a href="http://org.eclipse.ui.intro/showPage?id=concept3">Learn about Concept Three...</a>
  	</h4>
</body>
</html>

• launch a runtime-workbench with the product id of the product you created to see the extension to the Hello World intro. We simply contributed a third topic to the root page that launches the contributed page, id="concept3" :

• the content of the third page uses the include and the contentProvider elements to include the first link from the root page, and to print the current time. It is as follows :

• this is what the above page would look like after the intro elements in it have been resolved. Notice the topic from the root page, and notice the current time :

Document Conformance and file name extensions

• All documents used as intro pages must be valid XHTML 1.0 documents. XHTML markup can be validated using w3.org validators.
• For conformance with existing HTML 4.0.1 browsers and to avoid running into any compatibility issues, authors are encouraged to follow the compatibility guidelines document in the XHTML 1.0 specs. By doing so, an XHTML 1.0 page is nothing but well-formed xml html. 
• All XHTML documents must be UTF-8 encoded and the XML declaration (e.g.: <?xml version="1.0" encoding="UTF-8" ?>)  must be avoided. This is a design/technical issue that is still evolving.