platform-help-home/proposals/xhtml/index.htm
Parent Directory
| 
Revision Log
Revision 1.2 -
(download)
(as text)
(annotate)
Thu Feb 17 17:06:33 2005 UTC (4 years, 9 months ago) by dejan
Branch: MAIN
Changes since 1.1: +373 -1 lines
Thu Feb 17 17:06:33 2005 UTC (4 years, 9 months ago) by dejan
Branch: MAIN
Changes since 1.1: +373 -1 lines
*** empty log message ***
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Welcome Framework Enhancements</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<link href="../Eclipse%20Doc%20Template/Eclipse%20Projects_files/dynamic_capabilities_files/default_style.css" type="text/css" rel="stylesheet" />
<script type="text/javascript" language="JavaScript">
<!--
function FP_changeProp() {//v1.0
var args=arguments,d=document,i,j,id=args[0],o=FP_getObjectByID(id),s,ao,v,x;
d.$cpe=new Array(); if(o) for(i=2; i<args.length; i+=2) { v=args[i+1]; s="o";
ao=args[i].split("."); for(j=0; j<ao.length; j++) { s+="."+ao[j]; if(null==eval(s)) {
s=null; break; } } x=new Object; x.o=o; x.n=new Array(); x.v=new Array();
x.n[x.n.length]=s; eval("x.v[x.v.length]="+s); d.$cpe[d.$cpe.length]=x;
if(s) eval(s+"=v"); }
}
function FP_getObjectByID(id,o) {//v1.0
var c,el,els,f,m,n; if(!o)o=document; if(o.getElementById) el=o.getElementById(id);
else if(o.layers) c=o.layers; else if(o.all) el=o.all[id]; if(el) return el;
if(o.id==id || o.name==id) return o; if(o.childNodes) c=o.childNodes; if(c)
for(n=0; n<c.length; n++) { el=FP_getObjectByID(id,c[n]); if(el) return el; }
f=o.forms; if(f) for(n=0; n<f.length; n++) { els=f[n].elements;
for(m=0; m<els.length; m++){ el=FP_getObjectByID(id,els[n]); if(el) return el; } }
return null;
}
// -->
</script>
</head>
<body bgcolor="#ffffff" style="position: relative; left: 0; top: 0">
<table width="100%">
<tr>
<td style="BACKGROUND: #0080c0"><span style="color: #FFFFFF"><b>Intro</b></span></td>
</tr>
</table>
<h1>XHTML support in the Welcome Framework.</h1>
<blockquote>
<b>Summary</b><br />
This document describes the new <a href="http://www.w3.org/TR/xhtml1/">XHTML
1.0</a> support in the Eclipse 3.1 Welcome framework. This new feature is still
evolving, and feedback is welcomed.<p><font size="-1">Last modified: Feb 17,
2005</font></p>
<p> </p>
</blockquote>
<p></p>
<h3>Background </h3>
<p>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: </p>
<ul>
<li>include content from other welcome pages.</li>
<li>contribute content to another welcome pages. </li>
<li>have content
<a href="javascript:;" onclick="FP_changeProp(/*id*/'tooltip4',0,'style.display','inline')">
<span style="cursor:help; text-decoration: none;">programmatically injected
</span></a>into it.
<span id="tooltip4" style="position: relative; display:none;" onclick="FP_changeProp(/*id*/'tooltip4',0,'style.display','none')">
<font color="#0000FF" style="cursor: hand;">(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.)</font></span></li>
</ul>
<p>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. </p>
<p> </p>
<h3>Proposed Solution</h3>
<p>Intro content will now be contributed with
<a href="javascript:;" onclick="FP_changeProp(/*id*/'tooltip1',0,'style.display','inline')">
<span style="cursor: help; text-decoration: none;">XHTML 1.0 documents</span></a>
<span id="tooltip1" style="position: relative; display:none;" onclick="FP_changeProp(/*id*/'tooltip1',0,'style.display','none')">
<font color="#0000FF" style="cursor: hand;">(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.)</font></span>.
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 <code>include</code>, <code>anchor</code>, and <code>
contentProvider</code>.
</p>
<ul>
<li> <code><b>include</b>: </code>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.</li>
</ul>
<blockquote>
<dl>
<dd>e.g.: <code><include path="root/foo" /></code> will include an element
with id <code>foo</code> from a welcome page with id <code>root</code>.
</dd>
</dl>
</blockquote>
<ul>
<li> <code><b>anchor</b>: </code>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.</li>
</ul>
<blockquote>
<dl>
<dd>e.g.: <code><anchor id="anchor1" /></code> will allow for
contribution into this page from other plugins. </dd>
</dl>
</blockquote>
<ul>
<li><code><b>contentProvider</b>: </code>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.
</li>
</ul>
<dl>
<dd>
<dl>
<dd>e.g.: <code><contentProvider id="contentProviderId"
class="org.eclipse.ui.intro.template2.IntroXHTMLContentProvider"
pluginId="org.eclipse.ui.intro.template2"> </contentProvider> <br>
</code> will allow for dynamic content to be generated from the <code>
org.eclipse.ui.intro.template2.IntroXHTMLContentProvider</code> class.</dd>
</dl>
</dd>
</dl>
<p>With these three elements, XHTML pages can be used to assemble a pluggable
and dynamic welcome experience.</p>
<p></p>
<p></p>
<blockquote>
<address><b><span style="font-variant: small-caps">Note</span>: </b>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:<br /><code> <introContent><br /> <page id="homePageId" url="http://eclipse.org"/><br /> <page id="standbyPageId" url="./static001/standby.html"/><br /> </introContent></code>
</address>
<address>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.
</address>
<address>
</address>
</blockquote>
<h3> </h3>
<h3>Hello World Sample</h3>
<p>Here are the steps to create a Hello World XHTML Welcome page : </p>
<ul>
<li><b>contribute a product </b>:</li>
</ul>
<dl>
<dd>
<pre><code><extension id="<i>product</i>"</code><a href="javascript:;" onclick="FP_changeProp(/*id*/'tooltip5',0,'style.display','inline')"><span style="cursor: help; text-decoration: none;"><sup>1</sup></span></a> <span id="tooltip5" style="position: relative; display:none;" onclick="FP_changeProp(/*id*/'tooltip5',0,'style.display','none')"><font color="#0000FF" style="cursor: hand;">(<i>italic</i> means a user specified value) </font></span><code>point="org.eclipse.core.runtime.products">
<product name="<i>%example.product.name</i>"
application="<i>org.eclipse.ui.ide.workbench</i>">
</product>
</extension></code></pre>
</dd>
</dl>
<ul>
<li><b>contribute an intro part and bind it to the product you just created
</b>:</li>
</ul>
<blockquote>
<pre><code><extension point="org.eclipse.ui.intro">
<intro
class="org.eclipse.ui.intro.config.CustomizableIntroPart"
id="<i>org.eclipse.ui.intro.template2.introId</i>">
</intro>
<introProductBinding
introId="<i>org.eclipse.ui.intro.template2.introId</i>"
productId="<i>org.eclipse.ui.intro.template2.product</i>">
</introProductBinding>
</extension> </code></pre>
</blockquote>
<ul>
<li><b>contribute a config (configuration) to the intro part you just
created :</b></li>
</ul>
<blockquote>
<pre><code><extension point="org.eclipse.ui.intro.config">
<config id = "<i>template2_configId</i>"
introId="<i>org.eclipse.ui.intro.template2.introId</i>"
content="<i>introContent.xml</i>">
<presentation home-page-id="<i>root</i>">
<implementation kind="html"/>
</presentation>
</config>
</extension> </code></pre>
</blockquote>
<ul>
<li><b>create an intro content file, introContent.xml, that describes all
your pages, and that you referenced in your intro configuration :</b></li>
</ul>
<blockquote>
<pre><code><?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></code></pre>
</blockquote>
<ul>
<li><b>create the actual XHTML pages referenced by the content file. Here is
root.xhtml : </b></li>
</ul>
<blockquote>
<pre><code><!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>
<b><anchor id="anchor1" /></b>
</body>
</html></code></pre>
</blockquote>
<ul>
<li><b>launch a runtime-workbench with the product id you just created to
see the simple intro :</b></li>
</ul>
<blockquote>
<p><code><img border="0" src="index.1.jpg"><br>
<br>
</code></p>
<p> </p>
</blockquote>
<h3>Extending the Hello World Sample</h3>
<p>Here are the steps to contribute to the above Hello World intro sample : </p>
<ul>
<li><b>contribute a configExtension declaring that you want to extend the
original configuration </b>:</li>
</ul>
<dl>
<dd>
<pre><code><extension point="org.eclipse.ui.intro.configExtension">
<configExtension configId="<i>template2_configId</i>"
content="<i>ext.xml</i>"/>
</extension> </code></pre>
</dd>
</dl>
<ul>
<li><b>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 : </b></li>
</ul>
<blockquote>
<pre><code><?xml version="1.0" encoding="utf-8" ?>
<introContent>
<extensionContent content="content/extContent.xhtml" path="root/anchor1" />
<page id="concept3" content="content/concept3.xhtml"/>
</introContent></code></pre>
</blockquote>
<ul>
<li><b>create the actual extension content, and save it as a separate file,
extContent.xml :</b></li>
</ul>
<blockquote>
<pre><code><!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></code></pre>
</blockquote>
<ul>
<li><b>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, <code>
id="concept3" </code>:</b></li>
</ul>
<blockquote>
<p><img border="0" src="index.2.jpg"></p>
</blockquote>
<p> </p>
<ul>
<li><b>the content of the third page uses the <code>include</code> and the
<code>contentProvider</code> elements to include the first link from the
root page, and to print the current time. It is as follows : </b></li>
</ul>
<blockquote>
<p>
<iframe name="I1" src="concept3XHTML.htm" width="100%" height="280" style="border: 1px solid #FFFFFF">
Your browser does not support inline frames or is currently configured not to display inline frames.
</iframe></p>
</blockquote>
<p> </p>
<ul>
<li><b>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 : </b></li>
</ul>
<blockquote>
<p><img border="0" src="index.3.jpg"></p>
</blockquote>
<p> </p>
<h3>Setup needed temporarily for M5 :</h3>
<p>Since all XHTML intro files are loaded with an xml parser, they have to be
well-formed
XML files. The process of loading an XML file validates the xml files for conformance
(even in the case of an non-validating XML parser). This mean that the DTD from
the XHTML 1.0 specs need to be local, for the intro parser to use them. A special EntityResolver handler had
to be written the point the DOCTYPE url to these local DTDs. </p>
<p>However, for M5, these dtds are not available yet, and they have to be
downloaded and unzip in a local temp folder. Here are the steps to get XHTML
support setup for M5: </p>
<ul>
<li>download and unzip <b>xhtml1.zip</b> from
<a href="http://www.w3.org/TR/xhtml1/#dtds">
http://www.w3.org/TR/xhtml1/#dtds</a> into any temp directory.</li>
<li>you need to pass -<b>DdtdBaseLocation</b>=<folder where you unzipped
above dtd file>. e.g.: -DdtdBaseLocation=D:\temp when you self host.</li>
</ul>
<p> </p>
<h3>Document Conformance and file name extensions</h3>
<ul>
<li>All documents used as intro pages must be valid XHTML 1.0 documents. XHTML
markup can be validated using w3.org <a href="http://validator.w3.org/">validators</a>.</li>
<li>For conformance with existing HTML 4.0.1 browsers and to avoid running into
any compatibility issues, authors are encouraged to follow the
<a href="http://www.w3.org/TR/xhtml1/#guidelines">compatibility guidelines</a>
document in the XHTML 1.0 specs. By doing so, an XHTML 1.0 page is nothing but
well-formed xml html. </li>
<li>For M5, all XHTML documents must be UTF-8 encoded and the
<a href="javascript:;" onclick="FP_changeProp(/*id*/'tooltip2',0,'style.display','inline')">
<span style="cursor: help; text-decoration: none">XML declaration </span>
</a>
<span id="tooltip2" style="position: relative; display:none; cursor: hand;" onclick="FP_changeProp(/*id*/'tooltip2',0,'style.display','none')">
<font color="#0000FF">(e.g.: <?xml version="1.0" encoding="UTF-8" ?>)</font>
</span> must be avoided. This is a design/technical issue that is still evolving.
<p></p>
<h3> </h3>
</li>
</ul>
</body>
</html>
| help@eclipse.org | ViewVC Help |
| Powered by ViewVC 1.0.3 |