forked from x-tag/x-tag
/
index.html
367 lines (322 loc) · 10.1 KB
/
index.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
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>X-Tag - a cross-browser web components library</title>
<link href="demo/images/shortcut.png" rel="shortcut icon" type="image/x-icon" />
<link rel="stylesheet" type="text/css" href="demo/css/reset.css" />
<link href='http://fonts.googleapis.com/css?family=Days+One|Righteous' rel='stylesheet' type='text/css'>
<link rel="stylesheet" type="text/css" href="demo/highlight/styles/vs.css" />
<link rel="stylesheet" type="text/css" href="demo/css/global.css"/>
</head>
<body>
<header>
<h1 id="logo"><<span>x</span>></h1>
<nav id="global_menu">
<a href="#menu">
<div>═</div><br /><div>═</div>
<nav id="global_nav" class="small-nav">
<a href="#intro">Intro</a>
<a href="#docs">Docs</a>
<a href="#examples">Examples</a>
</nav>
</a>
</nav>
<a href="https://twitter.com/share" class="twitter-share-button" data-url="http://mozilla.github.com/x-tag/" data-via="csuwldcat" data-hashtags="WebComponents">Tweet</a>
</header>
<div class="max-width">
<h2 id="tag_line">Custom HTML elements for modern browsers.</h2>
<h3>
Intro
<span id="intro" class="anchor-id"></span>
</h3>
<dl>
<dt>What it Does</dt>
<dd>
<p>
When you need an advanced HTML element for your app - <i>like a tabbox, tree,
special input, etc.</i> - you're probably familiar with this process:
</p>
<ol>
<li>scour the web for a plugin</li>
<li>add the plugin script include to your page</li>
<li>copy an element, or block of elements, into your markup</li>
<li>create a script block or include for your own code</li>
<li>write JavaScript to select elements on page load</li>
<li>instantiate a script to augment the existing vanilla markup</li>
<li>wash, rinse, repeat for every plugin you need</li>
</ol>
<p>
But what if all you had to do was:
</p>
<ol>
<li>Define your own HTML tag</li>
<li>Use it as you would any native tag</li>
<li><i>There is no step 3, it all Just Works™</i></li>
</ol>
<p>
Welcome to <span class="font">X-Tag</span> folks.
</p>
</dd>
<dt>How it Works</dt>
<dd>
<p>
In order to allow for the recognition and parsing of custom HTML tags, <span class="font">X-Tag</span> utilizes
a special CSS event mechanism to listen for the creation/parsing of new custom elements (details <a target="_blank" href="http://www.backalleycoder.com/2012/04/25/i-want-a-damnodeinserted/">here</a>).
This event is fired and processed by <span class="font">X-Tag</span> regardless of whether the element is present
in the source of the document, added by setting <code>innerHTML</code>, or generated dynamically using <code>document.createElement</code>.
When the element is initially created, <span class="font">X-Tag</span> inflates it and calls the <code>onCreate</code>
lifecycle function. <span class="font">X-Tag</span> also provides an <code>onInsert</code> lifecycle function that is run each time
the element is injected into the DOM. Here's an example with some comments for a bit more clarity:
</p>
<pre>
<code>
xtag.register('accordion', {
onCreate: function(){
// fired once at the time a component
// is initially created or parsed
},
onInsert: function(){
// fired each time a component
// is inserted into the DOM
},
events: {
'click:delegate(x-toggler)': function(){
// activate a clicked toggler
}
},
getters: {
'togglers': function(){
// return all toggler children
}
},
setters: {
// Add DOM object setters
},
methods: {
nextToggler: function(){
// activate next toggler
},
previousToggler: function(){
// activate the previous toggler
}
}
});
</code>
</pre>
</dd>
<dt>Browser Support</dt>
<dd>
X-Tag is compatible with the following browser versions:
<div id="browser_logos">
<a target="_blank" href="http://www.mozilla.org/en-US/firefox/new/">
<img src="demo/images/firefox.png" />
Firefox 5+ <span>desktop & mobile</span>
</a>
<a target="_blank" href="https://www.google.com/intl/en/chrome/browser/">
<img src="demo/images/chrome.png" />
Chrome 4+, Android 2.1+
</a>
<a target="_blank" href="http://www.apple.com/safari/download/">
<img src="demo/images/safari.png" />
Safari 4+ <span>desktop & mobile</span>
</a>
<a target="_blank" href="http://ie.microsoft.com/testdrive/info/downloads/">
<img src="demo/images/ie.png" />
Internet Explorer 9+
</a>
<a target="_blank" href="http://www.opera.com/browser/next/">
<img src="demo/images/opera.png" />
Opera 11+ <span>desktop & mobile</span>
</a>
</div>
</dd>
<dt>Pushing the Standard</dt>
<dd>
<p>
X-Tag is based on the Custom Elements portion of the <a target="_blank" href="http://www.w3.org/TR/2012/WD-components-intro-20120522/#custom-element-section">W3 Web Components spec</a>.
As <code>document.register</code> is solidified and implemented
(Firefox and Chrome are working on it) X-Tag will begin to take advantage
of the native method internally and introduce a global <code>document</code>
method to polyfill X-Tag-capable browsers.
<p>
</dd>
</dl>
<h3>
Docs
<span id="docs" class="anchor-id"></span>
</h3>
<dl id="doc_list">
<dt>Custom Tag Registration</dt>
<dd>
<h4><code>content</code><span>string</span></h4>
<p>
The content property on the tag registration object allows you to declare
default innerHTML for your component, similar to Shadow DOM elements in highlighted
in the W3 Web Components draft.
</p>
<pre>
<code>
xtag.register('superinput', {
content: '<input type="text" />'
});
</code>
</pre>
</dd>
<dd>
<h4><code>onCreate</code><span>function</span></h4>
<p>
Whenever a tag is recognized and parsed on load or generated using
<code>document.createElement</code>, an onCreate function is called
allowing you to modify the element before any other code is applied to it.
</p>
<pre>
<code>
xtag.register('superinput', {
onCreate: function(){
// superinputs begin life knowing they're super.
this.value = 'super';
}
});
</code>
</pre>
</dd>
<dd>
<h4><code>onInsert</code><span>function</span></h4>
<p>
The onInsert method is called everytime a given component's DOM element
is added to the DOM. This allows you to do things like check the state or
structure of the surrounding DOM tree or window scope and modify your
component accordingly.
</p>
<pre>
<code>
xtag.register('superinput', {
onInsert: function(){
// superinputs announce their arrival in the DOM like a boss!
alert("Yeah, that's right, superinput comin' thro'!");
}
});
</code>
</pre>
</dd>
<dd>
<h4><code>getters</code><span>object</span></h4>
<p>
The getter object provides native value retrieval handlers
to your component. For example: if a user caches a component's value,
<code>var value = element.value;</code> your
getter would have the oppertunity to fetch that value from anywhere
you'd like and even modify it before returning.
</p>
<pre>
<code>
xtag.register('superinput', {
getters: {
value: function(){
// everything superinputs do has a little super mixed in ;)
return this.value + ' is super';
}
}
});
</code>
</pre>
</dd>
<dd>
<h4><code>setters</code><span>object</span></h4>
<p>
The setters object is a shortcut for easy attachements of JavaSript accessors to the DOM element of
your component. For instance, when an user writes the code <code>element.src = "http://somesrc.com"</code>
your setter would be called with the provided string value giving you a chance to
manipulate the string or change properties on the element.
</p>
<pre>
<code>
xtag.register('superinput', {
setters: {
value: function(value){
// boy, these superinputs sure are loud little buggers.
alert(value);
this.value = value;
}
}
});
</code>
</pre>
</dd>
<dd>
<h4><code>events</code><span>object</span></h4>
<p>
The events object allows you to bind events to the component at the time of creation.
Pseudo events like delegation are supported, additional pseudos can be added to
the <code>pseudos</code> object on the global <code>xtag</code> variable.
</p>
<pre>
<code>
xtag.register('superinput', {
events: {
focus: function(){
// what should superinputs do when they're in the spotlight?
}
}
});
</code>
</pre>
</dd>
<dd>
<h4><code>mixins</code><span>array</span></h4>
<p>
The mixins array allows you specify mixin keys that map to collections of getters, setters,
events, and lifecycle functions. X-Tag merges mixins into your component definition object for you.
Mixins are found on the <code>mixins</code> object of the global <code>xtag</code> variable -
you can add your own mixins there too!
</p>
<pre>
<code>
xtag.register('superinput', {
mixins: ['superdefaults']
});
</code>
</pre>
</dd>
</dl>
<h3>
Examples
<span id="examples" class="anchor-id"></span>
</h3>
<dl>
<dt>Supported Components</dt>
<dd>
<p>
We've created a <a href="demo.html">few examples</a> that demonstrate the kinds of components you can create.
Check out our <a href="demo.html#accordion">Accordion</a>, <a href="demo.html#tabbox">Tabbox</a>
or <a href="demo.html#flipbox">Flipbox</a> components.
</p>
</dd>
<dt>Community-driven Components</dt>
<dd>
<p>
We're working on a simple system developers can use to submit and share components (think NPM), check back soon!
</p>
</dd>
</dl>
</div>
<footer>
</footer>
</body>
<script type="text/javascript" src="demo/highlight/highlight.pack.js"></script>
<script type="text/javascript">
(function(){
var code = Array.prototype.slice.call(document.body.querySelectorAll('pre code'), 0),
count = code.length;
while(count--){
var text = code[count].innerHTML;
code[count].innerHTML = '';
code[count].textContent = text;
};
hljs.tabReplace = ' ';
hljs.initHighlightingOnLoad();
})();
</script>
<script id="twitter-wjs" type="text/javascript" src="http://platform.twitter.com/widgets.js"></script>
</html>