/
XBL-doc.html
272 lines (210 loc) · 15.2 KB
/
XBL-doc.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>IEtoW3C.js Documentation</title>
<style type="text/css">
body {font-family:sans-serif; padding:0; margin:.5em 2em;}
h1 {font-size:1.5em; font-weight:bold; border-bottom:3px double; padding-bottom:.5em;}
h2 {font-size:1.2em; font-weight:bold; background:#EEE; padding:0 .5em; border:1px solid #CCC;}
h3 {font-size:1em; font-weight:bold;}
p, ul {margin-bottom:1em;}
code.block {display:block;}
dt {font-weight:bold;}
</style>
</head>
<body>
<h1>XBL.js Documentation</h1>
<p><a href="XBL.js">The Script Source</a></p>
<h2>What It Does:</h2>
<p>This script implements the eXtensible Binding Language (XBL) in <acronym title="Microsoft Internet Explorer">MSIE</acronym> on Windows. I hope to add support for other browsers in the future.</p>
<p>XBL, if you're unfamiliar, is an XML-based language for specifying complex implementations of XML/HTML elements. By attaching an XBL binding to an element (through <acronym title="Cascading Style Sheets">CSS</acronym>), that element automatically obtains all the properties, methods, event handlers, and content specified by the binding. This makes XBL extremely powerful for creating reusable widgets and behaviors without polluting your document with scripts and presentational markup.</p>
<p>Despite its power and flexibility, XBL remains unused on the Web, mostly because it is only implemented in browsers based on Mozilla.org's Gecko rendering engine. By using this script, XBL (or at least a subset thereof) will work in a much larger pool of browsers and therefore can become viable for widespread use.</p>
<h2>How To Use It:</h2>
<p>Include the following script reference in the head of your document:</p>
<pre><code><script type="text/javascript" src="path/to/XBL.js"></script></code></pre>
<p>Then, once you have created your XBL binding(s), attach them to elements using the <code>-moz-binding</code> CSS property, for example:</p>
<pre><code><style type="text/css">
.binding-class {-moz-binding:url(BindingDocument.xml#bindingID);}
</style></code></pre>
<p>For more information on creating XBL bindings see the <a href="http://www.mozilla.org/catalog/architecture/xbl/">documentation on Mozilla.org</a>, especially the <a href="http://www.xulplanet.com/tutorials/xultu/introxbl.html">Introduction to XBL at XULPlanet</a>.</p>
<p><strong>Note:</strong> Some XBL features may not behave as expected using this implementation. See "Caveats" below for details.</p>
<h2>Implementation:</h2>
<p>Because there are significant differences between the <a href="http://www.mozilla.org/projects/xbl/xbl.html">XBL 1.0 Spec</a> submitted to the W3C and what Mozilla actually implements, I had to choose what to support. I decided that for the time being it would be best to attempt to follow Mozilla's implementation to preserve interoperability. I therefore worked mostly from <a href="http://www.xulplanet.com">XULPlanet</a>'s documentation. Some features unique to the XBL 1.0 Spec may have crept in to my implementation where useful.</p>
<p>Here is a listing of all the XBL features, along with what works and what doesn't (to my best knowledge).</p>
<dl>
<dt><binding id=""/></dt>
<dd>
<dl>
<dt>extends=""</dt>
<dd>This works properly (that I can tell) for inheriting implementations and handlers. It currently does not work properly for content; the base binding's content should be ignored but currently is not. Avoid using content sections in inherited bindings.</dd>
<dt>display=""</dt>
<dd>Not supported and will not be.</dd>
<dt><resources/>
<dd>
<dl>
<dt><image src=""/></dt>
<dd>Supported for preloading images.</dd>
<dt><stylesheet/></dt>
<dd>Not supported.</dd>
</dl>
</dd>
<dt><implementation/></dt>
<dd>
<dl>
<dt>implements=""</dt>
<dd>Not supported and will not be.</dd>
<dt><field name=""/></dt>
<dd>Supported. The content of this element is evaluated as a script and the result is assigned as the field's default value.</dd>
<dt><property name=""/></dt>
<dd>
<dl>
<dt><getter/> or onget=""</dt>
<dd>Not supported for the most part; the only thing it is used for is for setting the property's initial "value". See the section in "Caveats" about property getters/setters.</dd>
<dt><setter/> or onset=""</dt>
<dd>Supported somewhat. See the section in "Caveats" about property getters/setters for details.</dd>
</dl>
</dd>
<dt><method name=""><parameter name=""/><body>...</body></method></dt>
<dd>Supported.</dd>
<dt><constructor/></dt>
<dd>Supported.</dd>
<dt><destructor/></dt>
<dd>Not supported.</dd>
</dl>
</dd>
<dt><handlers/>
<dd>
<dl>
<dt><handler event=""/></dt>
<dd>
Supported, but only for events defined in the IE DHTML model. Custom events will not be handled.
<dl>
<dt>action="" (or content of handler element)</dt>
<dd>Supported. The <code>event</code> object will differ between IE and DOM2Events-compliant browsers as usual.</dd>
<dt>button=""</dt>
<dd>Supported, though the integer values for this currently map to different buttons than the standard. Avoid using this for now.</dd>
<dt>charcode=""</dt>
<dd>Not supported.</dd>
<dt>clickcount=""</dt>
<dd>Not supported.</dd>
<dt>keycode=""</dt>
<dd>Supported, though the keycode values may differ in IE's model.</dd>
<dt>modifiers=""</dt>
<dd>Supported. I map "meta" to the Alt key and "accel" to the Control key; if these should be mapped differently I welcome corrections.</dd>
<dt>phase=""</dt>
<dd>Supported only for "target"; "capturing" is not supported because IE's event model does not include a capturing phase.</dd>
<dt>preventdefault=""</dt>
<dd>Supported, to the best of my knowledge.</dd>
<dt>command=""</dt>
<dd>Not supported and will not be. (Only makes sense in a XUL chrome environment)</dd>
</dl>
</dd>
</dl>
</dd>
<dt><content/></dt>
<dd>Content is generated as explicit content (rather than anonymous content) and children are moved to a single insertion point. See "Caveats" section for things to keep in mind when working with this generated content.
<dl>
<dt><children/></dt>
<dd>A single insertion point for children is supported. The includes="" attribute for child insertion filtering is not supported.</dd>
</dl>
</dd>
</dl>
</dd>
<dt>DOM Interfaces:</dt>
<dd>
<dl>
<dt>DocumentXBL</dt>
<dd>
<dl>
<dt>.getAnonymousNodes()</dt>
<dd>Supported, to a degree. If the <code><children/></code> insertion point is at the top-level (i.e. a direct child of the <code><content/></code> element) then the children will incorrectly appear in the nodelist returned by <code>.getAnonymousNodes()</code>.</dd>
<dt>.getBindingParent()</dt>
<dd>Supported.</dd>
<dt>.attachBinding()</dt>
<dd>Supported.</dd>
<dt>.detachBinding()</dt>
<dd>Not supported.</dd>
<dt>.loadBindingDocument()</dt>
<dd>Supported.</dd>
<dt>.bindingDocuments</dt>
<dd>Supported.</dd>
</dl>
</dd>
<dt>ElementXBL</dt>
<dd>
<dl>
<dt>.bindingOwner</dt>
<dd>Supported.</dd>
<dt>.attachBinding()</dt>
<dd>Supported.</dd>
<dt>.detachBinding()</dt>
<dd>Not supported.</dd>
</dl>
</dd>
<dt>Events:</dt>
<dd>
<dl>
<dt>bindingattached, bindingdetached</dt>
<dd>Not supported.</dd>
</dl>
</dd>
</dl>
</dd>
</dl>
<h2>Caveats:</h2>
<p>Some features of XBL can not easily be reproduced in MSIE's document model; therefore, you need to take the following into consideration when writing XBL bindings intended for use through this script:</p>
<h3>HTML Versus XML:</h3>
<p>This script has only been tested on HTML documents. Whether it works in XML documents is unknown, mostly because I haven't tested it. In order for it to work in XML, it requires a way to import and run the XBL.js script from the XML document, plus proper CSS selector matching on XML elements. I'm not familiar enough with IE's XML capabilities to know if these prerequisites exist.</p>
<h3>DHTML Object Model:</h3>
<p>IE notoriously doesn't support unknown elements in its DHTML object model. Therefore using custom elements as XBL-defined widgets in your HTML document probably won't work.</p>
<p>The same goes for events; creating a <code><handler/></code> for a custom event (one not defined as a standard IE DHTML event) will not work.</p>
<h3>Anonymous Content and the DOM:</h3>
<p>XBL has a unique concept of "anonymous content", in which the content specified by an XBL binding's <code><content/></code> section is invisible to the containing document's DOM. For example, a binding may insert content nodes in between the bound element and its children, yet the bound element's <code>.childNodes</code> property will still refer to its original children; the DOM does not see those anonymous nodes. There is no such concept in MSIE's object model, so this script instead inserts those "anonymous" nodes as explicit nodes in the DOM. Therefore, you cannot use <code>.childNodes</code> and other DOM features as you would in a "true" XBL implementation.</p>
<p>It is usually simple to work around this by doing a simple test, for example:</p>
<pre><code>var kid = this.firstChild; //original firstChild, for Mozilla:
if(kid.bindingOwner == this) {
// insert code to find real firstChild in IE
}</code></pre>
<p>What's going on above: The <code>.bindingOwner</code> property only exists on anonymous XBL content nodes, and points to the bound element. Therefore if the bound element's <code>firstChild</code> has a <code>.bindingOwner</code> pointing back to the bound element, you know that the anonymous content model is not supported and you can create a conditional statement to find the correct node. In this way a binding can function in both models.</p>
<h3>Time of Binding Attachment:</h3>
<p>Unlike Mozilla's XBL implementation which attached bindings to elements as soon as those elements are loaded, this library has to wait until the entire document is loaded. In some ways this makes things easier (you can be sure that everything is already there) but it is different nonetheless and must be taken into account.</p>
<h3>Dynamic Content:</h3>
<p>Currently elements dynamically created and inserted via DOM scripting will not get bindings attached if they match -moz-binding CSS rules; binding attachment only occurs when the document is initially loaded. I plan to add this capability in the future if possible.</p>
<h3>MSIE DOM Incompatibilities:</h3>
<p>It may be obvious but bears repeating that scripts within your XBL bindings must take into account MSIE's particular DOM quirks, omissions, and proprietary features. For example, IE's proprietary event model differs greatly from the W3C-standard DOM2 Events used in Mozilla, so you must take this into consideration within your XBL event handlers. This is no different than DOM scripting in other situations.</p>
<h2>Compatibility:</h2>
<p>Known to work in MSIE 5 and 6 on Windows. Technically, support for other browsers should be possible as long as they provide a way to import and read external XML files via script. I welcome assistance on adding support for other browsers.</p>
<h2>Demonstrations:</h2>
<p>The following XBL demonstrations are known to work in IE6/Win (using this script) and Mozilla-based browsers.</p>
<ul>
<li><a href="XBL-test.html">Test Cases</a> - (in progress, not all tests work.)</li>
<li><a href="EmailLink-test.html">Obfuscated Email Links</a> - Display obfuscated email addresses as mailto: links</li>
<li><a href="FisheyeMenu-test.html">Fisheye Menu (aka Mac OS X Dock)</a> - displays an HTML unordered nested list as a fisheye menu; also contains a binding that creates a control panel for changing properties of the menu. (Warning: crashes Mozilla <= 1.2 or so)</li>
<li><a href="TreeMenu-test.html">Tree Menu</a> - displays an HTML unordered nested list as a folding tree menu.</li>
<li><a href="Rollovers-test.html">Rollovers</a> - implements simple rollover image swapping, with preloading.</li>
<li><a href="TextSizeControl-test.html">Text Size Control</a> - Creates a control that allows the user to change the base text size of the page, and store that choice as a cookie.</li>
</ul>
<h2>To Do:</h2>
<ul>
<li>I would <em>love</em> to make this support XBL's anonymous content model; it's one of XBL's greatest strengths, keeping binding attachment side-effect-free... after all, a stylistic behavior should not alter the document structure. Technically I believe it should be possible to hack the IE DOM to support anonymous content: upon binding attachment I'd have to store the element's .childNodes, .parentNode, etc. initial properties, then override all the native DOM methods (and property getters/setters -- would require using HTC) with ones that take the anonymous content nodes into account. It is debatable whether this would be worth the trouble, since it would involve a <em>lot</em> of code, basically an entire DOM (re-)implementation. Such a reimplementation wouldn't extend to CSS matching, though this probably wouldn't be a huge problem since the only CSS selectors affected would be the child (>) and sibling (+) selectors, neither of which IE currently supports anyway.</li>
<li>The bindingattached and bindingdetached events are not fired; I believe the only way to get IE to support these custom events is to use HTCs, and I've been unable to find an efficient way of doing that so far. The <a href="http://lojjic.net/script-library/IEtoW3C-doc.html">IEtoW3C</a> library would probably work but it's inefficient.</li>
<li>Binding removal. This isn't a priority since even Mozilla has problems doing this.</li>
<li>Add any other unsupported features and fix partially supported ones.</li>
</ul>
<h2>License:</h2>
<p>The contents of this file are subject to the Mozilla Public License Version 1.1 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at <a href="http://www.mozilla.org/MPL/">http://www.mozilla.org/MPL/</a></p>
<p>Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF
ANY KIND, either express or implied. See the License for the specific language governing rights and
limitations under the License.</p>
<p>The Initial Developer of the Original Code is Jason Johnston (jj{at}lojjic[dot]net). Portions created by
the Initial Developer are Copyright (C) 2004 the Initial Developer. All Rights
Reserved.</p>
<!--
<p>Contributor(s):</p>
<ul>
<li>contributor name</li>
</ul>
-->
<p>This code is provided for you to use free of charge. If you find it useful please consider making a donation to help me continue to create tools like this one. You can find my contact info at <a href="http://lojjic.net">http://lojjic.net</a>.</p>
</body>
</html>