platform-help-home/proposals/xhtml/index.htm

Revision 1.3 - (view) (download) (as text)

1 :	dejan	1.2	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2 :			"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 :			<html>
4 :
5 :			<head>
6 :			<title>Welcome Framework Enhancements</title>
7 :			<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
8 :			<meta http-equiv="Content-Style-Type" content="text/css" />
9 :			<link href="../Eclipse%20Doc%20Template/Eclipse%20Projects_files/dynamic_capabilities_files/default_style.css" type="text/css" rel="stylesheet" />
10 :			<script type="text/javascript" language="JavaScript">
11 :			<!--
12 :			function FP_changeProp() {//v1.0
13 :			var args=arguments,d=document,i,j,id=args[0],o=FP_getObjectByID(id),s,ao,v,x;
14 :			d.$cpe=new Array(); if(o) for(i=2; i<args.length; i+=2) { v=args[i+1]; s="o";
15 :			ao=args[i].split("."); for(j=0; j<ao.length; j++) { s+="."+ao[j]; if(null==eval(s)) {
16 :			s=null; break; } } x=new Object; x.o=o; x.n=new Array(); x.v=new Array();
17 :			x.n[x.n.length]=s; eval("x.v[x.v.length]="+s); d.$cpe[d.$cpe.length]=x;
18 :			if(s) eval(s+"=v"); }
19 :			}
20 :
21 :			function FP_getObjectByID(id,o) {//v1.0
22 :			var c,el,els,f,m,n; if(!o)o=document; if(o.getElementById) el=o.getElementById(id);
23 :			else if(o.layers) c=o.layers; else if(o.all) el=o.all[id]; if(el) return el;
24 :			if(o.id==id \|\| o.name==id) return o; if(o.childNodes) c=o.childNodes; if(c)
25 :			for(n=0; n<c.length; n++) { el=FP_getObjectByID(id,c[n]); if(el) return el; }
26 :			f=o.forms; if(f) for(n=0; n<f.length; n++) { els=f[n].elements;
27 :			for(m=0; m<els.length; m++){ el=FP_getObjectByID(id,els[n]); if(el) return el; } }
28 :			return null;
29 :			}
30 :			// -->
31 :			</script>
32 :			</head>
33 :
34 :			<body bgcolor="#ffffff" style="position: relative; left: 0; top: 0">
35 :
36 :			<table width="100%">
37 :			<tr>
38 :			<td style="BACKGROUND: #0080c0"><span style="color: #FFFFFF"><b>Intro</b></span></td>
39 :			</tr>
40 :			</table>
41 :			<h1>XHTML support in the Welcome Framework.</h1>
42 :			<blockquote>
43 :			<b>Summary</b><br />
44 :			This document describes the new <a href="http://www.w3.org/TR/xhtml1/">XHTML
45 :			1.0</a> support in the Eclipse 3.1 Welcome framework. This new feature is still
46 :			evolving, and feedback is welcomed.<p><font size="-1">Last modified: Feb 17,
47 :			2005</font></p>
48 :			<p> </p>
49 :			</blockquote>
50 :			<p></p>
51 :			<h3>Background </h3>
52 :			<p>In Eclipse SDK 3.0, a new welcome framework was introduced to replace the existing
53 :			editor-based welcome framework. It allowed for authoring Welcome pages using custom
54 :			Intro XML markup. This kept content completely separate from presentation, which
55 :			in turn was solely controlled by CSS or .properties files. A custom markup language
56 :			was introduced to allow for the dynamic contribution to a given welcome page. This
57 :			pluggable architecture for a given welcome page was needed to follow the same dynamic
58 :			plugin nature of the platform itself. That is, a page can: </p>
59 :			<ul>
60 :			<li>include content from other welcome pages.</li>
61 :			<li>contribute content to another welcome pages. </li>
62 :			<li>have content
63 :			<a href="javascript:;" onclick="FP_changeProp(/id/'tooltip4',0,'style.display','inline')">
64 :			<span style="cursor:help; text-decoration: none;">programmatically injected
65 :			</span></a>into it.
66 :			<span id="tooltip4" style="position: relative; display:none;" onclick="FP_changeProp(/id/'tooltip4',0,'style.display','none')">
67 :			<font color="#0000FF" style="cursor: hand;">(This content is typically the result
68 :			of some query to the workbench through java code. An interface in the intro
69 :			framework allows for dynamically interacting with the generated HTML page and
70 :			populating the html page with more content, on the fly. For example, a welcome
71 :			page can dynamically create and display a list of projects in the workbench.)</font></span></li>
72 :			</ul>
73 :			<p>These features where implemented in 3.0 using a custom intro XML markup, and
74 :			while the design satisfied the requirement, feedback pointed to the need for easier
75 :			authoring. One such usability enhancement is to allow Welcome pages to be created
76 :			by WYSIWYG editors, eliminating the need for the visual designer to know any details
77 :			about the internals of the Intro framework. Once created, these pages can then be
78 :			contributed as Welcome pages and assembled together into one coherent "out of the
79 :			box" experience. </p>
80 :			<p> </p>
81 :			<h3>Proposed Solution</h3>
82 :			<p>Intro content will now be contributed with
83 :			<a href="javascript:;" onclick="FP_changeProp(/id/'tooltip1',0,'style.display','inline')">
84 :			<span style="cursor: help; text-decoration: none;">XHTML 1.0 documents</span></a>
85 :			<span id="tooltip1" style="position: relative; display:none;" onclick="FP_changeProp(/id/'tooltip1',0,'style.display','none')">
86 :			<font color="#0000FF" style="cursor: hand;">(A reformulation of the three HTML 4
87 :			document types as applications of XML 1.0. For M5, only XHTML 1.0 is supported.
88 :			XHTML 1.1 (module-based XHTML) can be supported, based on feedback.)</font></span>.
89 :			The idea is to use the fact that XHTML is well formed XML and parse each document,
90 :			manipulating the DOM to allow for contributions and extensions to be merged.
91 :			Three xml elements from the 3.0 intro markup where used to extend the XHTML 1.0
92 :			element list. These where <code>include</code>, <code>anchor</code>, and <code>
93 :			contentProvider</code>.
94 :			</p>
95 :			<ul>
96 :			<li> <code><b>include</b>: </code>this element can be added to a valid
97 :			XHTML document to include content from another XHTML document. The content
98 :			to be included must be a valid XHTML snippet.</li>
99 :			</ul>
100 :			<blockquote>
101 :			<dl>
102 :			<dd>e.g.: <code><include path="root/foo" /></code> will include an element
103 :			with id <code>foo</code> from a welcome page with id <code>root</code>.
104 :			</dd>
105 :			</dl>
106 :			</blockquote>
107 :			<ul>
108 :			<li> <code><b>anchor</b>: </code>this element can be added to a valid XHTML
109 :			document to declare that content can be contributed to this page by other
110 :			welcome contributions. A page declares locations that are suitable to be
111 :			extended by defining these anchor points.</li>
112 :			</ul>
113 :			<blockquote>
114 :			<dl>
115 :			<dd>e.g.: <code><anchor id="anchor1" /></code> will allow for
116 :			contribution into this page from other plugins. </dd>
117 :			</dl>
118 :			</blockquote>
119 :			<ul>
120 :			<li><code><b>contentProvider</b>: </code>this element can be added to a valid XHTML
121 :			document to establish a hook into the workbench. When the intro framework
122 :			encounters this element, an interface is called allowing for the
123 :			manipulation of the DOM of the XHTML page.
124 :			</li>
125 :			</ul>
126 :			<dl>
127 :			<dd>
128 :			<dl>
129 :			<dd>e.g.: <code><contentProvider id="contentProviderId"
130 :			class="org.eclipse.ui.intro.template2.IntroXHTMLContentProvider"
131 :			pluginId="org.eclipse.ui.intro.template2"> </contentProvider> <br>
132 :			</code> will allow for dynamic content to be generated from the <code>
133 :			org.eclipse.ui.intro.template2.IntroXHTMLContentProvider</code> class.</dd>
134 :			</dl>
135 :			</dd>
136 :			</dl>
137 :			<p>With these three elements, XHTML pages can be used to assemble a pluggable
138 :			and dynamic welcome experience.</p>
139 :			<p></p>
140 :			<p></p>
141 :			<blockquote>
142 :			<address><b><span style="font-variant: small-caps">Note</span>: </b>if the only requirement is to render a tree of HTML documents
143 :			(from the file system or from the net), with no need for extensibility,
144 :			then this is already supported in Eclipse 3.0. A page can simply be defined
145 :			as follows:<br /><code>    <introContent><br />        <page id="homePageId" url="http://eclipse.org"/><br />        <page id="standbyPageId" url="./static001/standby.html"/><br />    </introContent></code>
146 :			</address>
147 :			<address>The html page is loaded from the specified url, and displayed in the Welcome
148 :			view as is. In this scenario, the html page can make use of the custom intro
149 :			url actions. The browser in the welcome "knows" how to interpret these urls
150 :			in a special way, allowing for interaction with the workbench from a static
151 :			html page.
152 :			</address>
153 :			<address>
154 :			</address>
155 :			</blockquote>
156 :			<h3> </h3>
157 :			<h3>Hello World Sample</h3>
158 :			<p>Here are the steps to create a Hello World XHTML Welcome page :  </p>
159 :			<ul>
160 :			<li><b>contribute a product </b>:</li>
161 :			</ul>
162 :			<dl>
163 :			<dd>
164 :			<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">
165 :			<product name="<i>%example.product.name</i>"
166 :			application="<i>org.eclipse.ui.ide.workbench</i>">
167 :			</product>
168 :			</extension></code></pre>
169 :			</dd>
170 :			</dl>
171 :			<ul>
172 :			<li><b>contribute an intro part and bind it to the product you just created
173 :			</b>:</li>
174 :			</ul>
175 :			<blockquote>
176 :			<pre><code><extension point="org.eclipse.ui.intro">
177 :			<intro
178 :			class="org.eclipse.ui.intro.config.CustomizableIntroPart"
179 :			id="<i>org.eclipse.ui.intro.template2.introId</i>">
180 :			</intro>
181 :			<introProductBinding
182 :			introId="<i>org.eclipse.ui.intro.template2.introId</i>"
183 :			productId="<i>org.eclipse.ui.intro.template2.product</i>">
184 :			</introProductBinding>
185 :			</extension> </code></pre>
186 :			</blockquote>
187 :			<ul>
188 :			<li><b>contribute a config (configuration) to the intro part you just
189 :			created :</b></li>
190 :			</ul>
191 :			<blockquote>
192 :			<pre><code><extension point="org.eclipse.ui.intro.config">
193 :			<config id = "<i>template2_configId</i>"
194 :			introId="<i>org.eclipse.ui.intro.template2.introId</i>"
195 :			content="<i>introContent.xml</i>">
196 :			<presentation home-page-id="<i>root</i>">
197 :			<implementation kind="html"/>
198 :			</presentation>
199 :			</config>
200 :			</extension> </code></pre>
201 :			</blockquote>
202 :			<ul>
203 :			<li><b>create an intro content file, introContent.xml, that describes all
204 :			your pages, and that you referenced in your intro configuration :</b></li>
205 :			</ul>
206 :			<blockquote>
207 :			<pre><code><?xml version="1.0" encoding="utf-8" ?>
208 :			<introContent>
209 :			<page id="root" content="content/root.xhtml"/>
210 :			<page id="concept1" content="content/concept1.xhtml"/>
211 :			<page id="concept2" content="content/concept2.xhtml"/>
212 :			</introContent></code></pre>
213 :			</blockquote>
214 :			<ul>
215 :			<li><b>create the actual XHTML pages referenced by the content file. Here is
216 :			root.xhtml :  </b></li>
217 :			</ul>
218 :			<blockquote>
219 :			<pre><code><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
220 :			"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
221 :			<html xmlns="http://www.w3.org/1999/xhtml">
222 :			<head>
223 :			<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
224 :			<title>root.xhtml</title>
225 :			<link rel="stylesheet" href="root.css" type="text/css" />
226 :			</head>
227 :			<body>
228 :			<h1>Welcome to Product A</h1>
229 :			<h4 id="firstH4">
230 :			<img border="0" src="welcome_item.gif" alt="Concept1" />
231 :			<a href="http://org.eclipse.ui.intro/showPage?id=concept1">Learn about Concept One...
232 :			</a>
233 :			</h4>
234 :			<h4>
235 :			<img border="0" src="welcome_item.gif" alt="Concept2" />
236 :			<a href="http://org.eclipse.ui.intro/showPage?id=concept2">Learn about Concept Two...</a>
237 :			</h4>
238 :			<b><anchor id="anchor1" /></b>
239 :			</body>
240 :			</html></code></pre>
241 :			</blockquote>
242 :			<ul>
243 :			<li><b>launch a runtime-workbench with the product id you just created to
244 :			see the simple intro :</b></li>
245 :			</ul>
246 :			<blockquote>
247 :			<p><code><img border="0" src="index.1.jpg"><br>
248 :			<br>
249 :			</code></p>
250 :			<p> </p>
251 :			</blockquote>
252 :			<h3>Extending the Hello World Sample</h3>
253 :			<p>Here are the steps to contribute to the above Hello World intro sample :  </p>
254 :			<ul>
255 :			<li><b>contribute a configExtension declaring that you want to extend the
256 :			original configuration </b>:</li>
257 :			</ul>
258 :			<dl>
259 :			<dd>
260 :			<pre><code><extension point="org.eclipse.ui.intro.configExtension">
261 :			<configExtension configId="<i>template2_configId</i>"
262 :			content="<i>ext.xml</i>"/>
263 :			</extension> </code></pre>
264 :			</dd>
265 :			</dl>
266 :			<ul>
267 :			<li><b>create the extension content file and declare what the
268 :			extension content is. extensionContent element specifies the location of the
269 :			content file and the target path where this extension content needs to be
270 :			inserted. If this new content needs to reference other pages, these pages
271 :			can be declared in the same extension content file, as below :  </b></li>
272 :			</ul>
273 :			<blockquote>
274 :			<pre><code><?xml version="1.0" encoding="utf-8" ?>
275 :			<introContent>
276 :			<extensionContent content="content/extContent.xhtml" path="root/anchor1" />
277 :			<page id="concept3" content="content/concept3.xhtml"/>
278 :			</introContent></code></pre>
279 :			</blockquote>
280 :			<ul>
281 :			<li><b>create the actual extension content, and save it as a separate file,
282 :			extContent.xml :</b></li>
283 :			</ul>
284 :			<blockquote>
285 :			<pre><code><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
286 :			"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
287 :			<html xmlns="http://www.w3.org/1999/xhtml">
288 :			<head>
289 :			<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
290 :			<title>root.xhtml</title>
291 :			<link rel="stylesheet" href="root.css" type="text/css" />
292 :			</head>
293 :			<body>
294 :			<h4>
295 :			<img border="0" src="welcome_item.gif" alt="Concept2" />
296 :			<a href="http://org.eclipse.ui.intro/showPage?id=concept3">Learn about Concept Three...</a>
297 :			</h4>
298 :			</body>
299 :			</html></code></pre>
300 :			</blockquote>
301 :			<ul>
302 :			<li><b>launch a runtime-workbench with the product id of the product you created
303 :			to see the extension to the Hello World intro. We simply contributed a third
304 :			topic to the root page that launches the contributed page, <code>
305 :			id="concept3" </code>:</b></li>
306 :			</ul>
307 :			<blockquote>
308 :			<p><img border="0" src="index.2.jpg"></p>
309 :			</blockquote>
310 :			<p> </p>
311 :			<ul>
312 :			<li><b>the content of the third page uses the <code>include</code> and the
313 :			<code>contentProvider</code> elements to include the first link from the
314 :			root page, and to print the current time. It is as follows : </b></li>
315 :			</ul>
316 :			<blockquote>
317 :			<p>
318 :			<iframe name="I1" src="concept3XHTML.htm" width="100%" height="280" style="border: 1px solid #FFFFFF">
319 :			Your browser does not support inline frames or is currently configured not to display inline frames.
320 :			</iframe></p>
321 :			</blockquote>
322 :			<p> </p>
323 :			<ul>
324 :			<li><b>this is what the above page would look like after the intro elements
325 :			in it have been resolved. Notice the topic from the root page, and notice
326 :			the current time : </b></li>
327 :			</ul>
328 :			<blockquote>
329 :			<p><img border="0" src="index.3.jpg"></p>
330 :			</blockquote>
331 :			<p> </p>
332 :			<h3>Document Conformance and file name extensions</h3>
333 :			<ul>
334 :			<li>All documents used as intro pages must be valid XHTML 1.0 documents. XHTML
335 :			markup can be validated using w3.org <a href="http://validator.w3.org/">validators</a>.</li>
336 :			<li>For conformance with existing HTML 4.0.1 browsers and to avoid running into
337 :			any compatibility issues, authors are encouraged to follow the
338 :			<a href="http://www.w3.org/TR/xhtml1/#guidelines">compatibility guidelines</a>
339 :			document in the XHTML 1.0 specs. By doing so, an XHTML 1.0 page is nothing but
340 :			well-formed xml html.  </li>
341 :	kkolosow	1.3	<li>All XHTML documents must be UTF-8 encoded and the
342 :	dejan	1.2	<a href="javascript:;" onclick="FP_changeProp(/id/'tooltip2',0,'style.display','inline')">
343 :			<span style="cursor: help; text-decoration: none">XML declaration </span>
344 :			</a>
345 :			<span id="tooltip2" style="position: relative; display:none; cursor: hand;" onclick="FP_changeProp(/id/'tooltip2',0,'style.display','none')">
346 :			<font color="#0000FF">(e.g.: <?xml version="1.0" encoding="UTF-8" ?>)</font>
347 :			</span> must be avoided. This is a design/technical issue that is still evolving.
348 :			<p></p>
349 :			<h3> </h3>
350 :			</li>
351 :			</ul>
352 :
353 :			</body>
354 :
355 :			</html>

help@eclipse.org	ViewVC Help
Powered by ViewVC 1.0.3

Eclipse

platform-help-home/proposals/xhtml/index.htm