Skip to content

Commit 967326a

Browse files
author
Ryan A. Johnson
committed
docs(install): correct and reformat install guide
1 parent b431843 commit 967326a

File tree

3 files changed

+200
-89
lines changed

3 files changed

+200
-89
lines changed

‎source/_templates/partials/after_footer.njk‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
1+
<!-- intelligently load ES5 Adapter (if needed) -->
2+
<span id="ce-es5-adapter">
3+
<script>
4+
if (!window.customElements) {
5+
var elAdapter = document.querySelector('#ce-es5-adapter');
6+
elAdapter.parentElement.removeChild(elAdapter);
7+
}
8+
</script>
9+
<script src="https://ab2b55b0a26bb32fdc01-2c8b94bcec8e01c366189541a4035ea4.ssl.cf5.rackcdn.com/custom-elements-es5-adapter.js"></script>
10+
</span>
11+
112
<script src="https://code.jquery.com/jquery-3.2.1.min.js"
213
integrity="sha256-hwg4gsxgFZhOsEEamdOYGBf13FyQuiTwlAQgxVSNgt4="
314
crossorigin="anonymous"></script>

‎source/_templates/partials/head.njk‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,6 @@
1616
<link rel="stylesheet" href="helix-ui.css">
1717
<link rel="stylesheet" href="docs.css">
1818

19-
<!-- ES5 Adapter -->
20-
<script src="https://ab2b55b0a26bb32fdc01-2c8b94bcec8e01c366189541a4035ea4.ssl.cf5.rackcdn.com/custom-elements-es5-adapter.js"></script>
2119
<!-- Polyfill Loader -->
2220
<script src="https://ab2b55b0a26bb32fdc01-2c8b94bcec8e01c366189541a4035ea4.ssl.cf5.rackcdn.com/webcomponents-loader.js"></script>
2321
</head>

‎source/guides/install/index.html‎

Lines changed: 189 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -2,136 +2,238 @@
22
title: Installing HelixUI
33
cdn: https://2d2bf231b82dfe76fe36-fa12562cfe810d69bedcc36a0ac289ef.ssl.cf1.rackcdn.com
44
---
5-
{% extends 'fullpage.njk' %}
5+
{% extends 'component.njk' %}
66
{% block content %}
77
<section>
88
<h2 class="hxSectionTitle" id="assets">Assets</h2>
9-
<table class="table table-condensed">
9+
<table class="hxTable hxTable--condensed">
1010
<thead>
1111
<tr>
12-
<th>File</th>
13-
<th>Testing</th>
14-
<th>Production (CDN)</th>
12+
<th></th>
13+
<th>Development (unminified)</th>
14+
<th>Production (minified)</th>
1515
</tr>
1616
</thead>
1717
<tbody>
1818
<tr>
19-
<th>bootstrap.helix.css</th>
19+
<th>Appearance</th>
2020
<td>
21-
<a href="/helix-ui/styles/bootstrap.helix.css" target="_blank">bootstrap.helix.css</a>
21+
<a href="{{page.cdn}}/css/helix-ui.css" target="_blank">
22+
<hx-icon type="external-link"></hx-icon>
23+
helix-ui.css
24+
</a>
2225
</td>
23-
<td>
24-
<a href="{{page.cdn}}/css/bootstrap.helix.css">HTTPS</a>
25-
</td>
26-
</tr>
27-
<tr>
28-
<th>helix-ui.css</th>
29-
<td>
30-
<a href="/helix-ui/styles/helix-ui.css" target="_blank">helix-ui.css</a>
31-
</td>
32-
<td>
33-
<a href="{{page.cdn}}/css/helix-ui.css">HTTPS</a>
34-
</td>
35-
</tr>
36-
<tr>
37-
<th>helix-ui.js</th>
38-
<td>
39-
<a href="/helix-ui/scripts/helix-ui.js" target="_blank">helix-ui.js</a>
40-
</td>
41-
<td>
42-
<a href="{{page.cdn}}/javascript/helix-ui.js" target="_blank">HTTPS</a>
43-
</td>
44-
</tr>
45-
<tr>
46-
<th>ES5 Adapter</th>
4726
<td>N/A</td>
48-
<td>
49-
<a href="{{page.cdn}}/javascript/custom-elements-es5-adapter.js" target="_blank">HTTPS</a>
50-
</td>
5127
</tr>
5228
<tr>
53-
<th>Web Components Polyfill Loader</th>
54-
<td>N/A</td>
29+
<th>Behavior</th>
5530
<td>
56-
<a href="{{page.cdn}}/javascript/webcomponents-loader.js" target="_blank">HTTPS</a>
31+
<a href="{{page.cdn}}/javascript/helix-ui.js" target="_blank">
32+
<hx-icon type="external-link"></hx-icon>
33+
helix-ui.js
34+
</a>
5735
</td>
36+
<td>N/A</td>
5837
</tr>
5938
</tbody>
6039
</table>
6140
</section>
6241

63-
<section>
42+
<section><!-- Web Components -->
43+
<h2 class="hxSectionTitle" id="web-components">Web Components</h2>
6444
<section>
65-
<h2 class="hxSectionTitle" id="web-components">Web Components</h2>
45+
<table class="hxTable hxTable--condensed">
46+
<thead>
47+
<tr>
48+
<th></th>
49+
<th>Production (CDN)</th>
50+
</tr>
51+
</thead>
52+
<tbody>
53+
<tr>
54+
<th>ES5 Adapter</th>
55+
<td>
56+
<a href="{{page.cdn}}/javascript/custom-elements-es5-adapter.js" target="_blank">
57+
<hx-icon type="external-link"></hx-icon>
58+
custom-elements-es5-adapter.js
59+
</a>
60+
</td>
61+
</tr>
62+
<tr>
63+
<th>Web Components Loader</th>
64+
<td>
65+
<a href="{{page.cdn}}/javascript/webcomponents-loader.js" target="_blank">
66+
<hx-icon type="external-link"></hx-icon>
67+
webcomponents-loader.js
68+
</a>
69+
</td>
70+
</tr>
71+
</tbody>
72+
</table>
6673

6774
<p>
6875
To begin using the custom elements defined in HelixUI, you must first
69-
ensure that the browser can load them. To do so, copy and paste the
70-
following to the bottom of the <code>&lt;head&gt;</code> in your applicaton.
76+
ensure that the browser can load them. To do so, you'll need to insert
77+
both the ES5 Adapter and the Polyfill Loader into your markup.
7178
</p>
79+
</section>
80+
81+
<section><!-- TL;DR -->
82+
<h3 class="hxSubSectionTitle">TL;DR</h3>
7283
{% code 'html' %}
73-
<!-- ES5 Adapter -->
74-
<script src="{{page.cdn}}/javascript/custom-elements-es5-adapter.js"></script>
75-
<!-- Polyfill Loader -->
76-
<script src="{{page.cdn}}/javascript/webcomponents-loader.js"></script>
84+
<html>
85+
<head>
86+
...
87+
88+
<script src="cdn/path/to/webcomponents-loader.js"></script>
89+
<!-- polyfills automatically injected here (if needed) -->
90+
</head>
91+
<body>
92+
...
93+
94+
<!-- intelligently load ES5 Adapter (if needed) -->
95+
<span id="ce-es5-adapter">
96+
<script>
97+
if (!window.customElements) {
98+
var elAdapter = document.querySelector('#ce-es5-adapter');
99+
elAdapter.parentElement.removeChild(elAdapter);
100+
}
101+
</script>
102+
<script src="cdn/path/to/custom-elements-es5-adapter.js"></script>
103+
</span>
104+
105+
<!-- HelixUI custom element definitions -->
106+
<script src="cdn/path/to/helix-ui.js"></script>
107+
108+
<!-- load your application logic here -->
109+
<script src="domain/path/to/your/app.js"></script>
110+
</body>
111+
</html>
77112
{% endcode %}
78113
</section>
79114

80-
<section>
81-
<h3 class="hxSubSectionTitle">ES5 Adapter</h3>
82-
<div class="alert alert-warning">
83-
<b>DO NOT attempt to concatenate or compile the adapter into ES5.</b>
84-
This will break the adapter logic.
85-
</div>
86-
<div class="alert alert-info">
87-
The adapter <em>will raise a syntax exception in browsers
88-
that do not support ES6 (e.g. IE)</em>. <br />
89-
This should not affect functionality of any web components.
90-
</div>
91-
<div class="alert alert-info">
92-
The ES5 adapter must be loaded before the Polyfill Loader.
115+
<section><!-- web components loader -->
116+
<h3 class="hxSubSectionTitle" id="web-components-loader">Web Components Loader</h3>
117+
<div class="hxAlert">
118+
<div class="hxAlert__icon">
119+
<hx-icon type="info-circle"></hx-icon>
120+
</div>
121+
<div class="hxAlert__text">
122+
<span class="hxAlert__status">NOTE</span>
123+
Currently, the loader only supports being loaded in the <code>&lt;head&gt;</code>
124+
of an HTML document.
125+
</div>
93126
</div>
127+
<br />
128+
94129
<p>
95-
To make sure that web components work in all supported browsers,
96-
we have to compile our definitions in ES5-compatible JavaScript.
97-
However, web component APIs require defining custom elements
98-
using ES6 class syntax.
130+
The web components loader comes from the
131+
<a href="https://github.com/webcomponents/webcomponentsjs">webcomponentsjs</a>
132+
project. Its job is to perform feature detection on the current browser
133+
so that it can dynamically inject the smallest polyfill needed to
134+
support web components into the head of the HTML document.
99135
</p>
100136
<p>
101-
This is where the ES5 adapter comes in. It wraps native APIs
102-
to make them compatible with ES5 browsers, but ensures that
103-
ES6-compatible browsers still follow spec.
137+
Once the polyfills are loaded (if needed), the "WebComponentsReady" event
138+
will be fired on the document to announce availability of Web Component
139+
functionality.
104140
</p>
141+
<ul>
142+
<li>
143+
<code>Array.from</code> is polyfilled along with the
144+
<code>webcomponents-lite.js</code> polyfill.
145+
</li>
146+
<li>
147+
A <a href="https://github.com/webcomponents/webcomponentsjs/pull/861">pull request</a>
148+
is open to allow inserting the loader in the <code>&lt;body&gt;</code>.
149+
</li>
150+
</ul>
151+
{% code 'html' %}
152+
<head>
153+
...
154+
155+
<script src="cdn/path/to/webcomponents-loader.js"></script>
156+
<!-- polyfills injected here (if needed) -->
157+
</head>
158+
{% endcode %}
105159
</section>
106160

107-
<section>
108-
<h3 class="hxSubSectionTitle">Polyfill Loader</h3>
109-
<div class="alert alert-info">
110-
Load the polyfill loader <em>after</em> the ES5 Adapter in the
111-
<code>&lt;head&gt;</code>.
112-
</div>
161+
<section><!-- ES5 Adapter -->
162+
<h3 class="hxSubSectionTitle" id="es5-adapter">ES5 Adapter</h3>
113163
<p>
114-
Using feature detection, the polyfill loader script will
115-
automatically determine the minimum polyfills needed for the
116-
user's browser. The loader will add the polyfills via an additional
117-
<code>&lt;script&gt;</code> to the <code>&lt;head&gt;</code>.
164+
The Custom Elements v1 spec requires that constructor classes be defined
165+
using ES6 class syntax. This is problematic, given that we have to
166+
support legacy browsers like Internet Explorer that do not support ES6.
118167
</p>
119168
<p>
120-
If the user's browser doesn't need any polyfills, this additional
121-
script will not be added.
169+
The ES5 Adapter corrects this problem by converting ES5 classes to ES6
170+
syntax so that modern browsers can load custom element definitions.
122171
</p>
123-
</section>
124-
125-
<section>
126-
<h3 class="hxSubSectionTitle">HelixUI Components</h3>
127-
<div class="alert alert-info">
128-
Load HelixUI components and your application JavaScript at the bottom
129-
of the <code>&lt;body&gt;</code> of your application.
130-
</div>
131172
<p>
132-
To ensure maximum compatibility, please make sure that HelixUI
133-
JavaScript is loaded after both the ES5 Adapter and the Polyfill Loader.
173+
A complication arises when a legacy browser tries to run the ES5 Adapter.
174+
Because the adapter is written in ES6 syntax, it will raise an exception
175+
in any browser that doesn't support ES6. To get around this we can wrap
176+
the injection of the ES5 adapter in a container that can be dynamically
177+
removed if it isn't needed.
134178
</p>
179+
180+
{% code 'html' %}
181+
<body>
182+
...
183+
184+
<!-- intelligently load ES5 Adapter (if needed) -->
185+
<span id="ce-es5-adapter">
186+
<script>
187+
if (!window.customElements) {
188+
var elAdapter = document.querySelector('#ce-es5-adapter');
189+
elAdapter.parentElement.removeChild(elAdapter);
190+
}
191+
</script>
192+
<script src="path/to/custom-elements-es5-adapter.js"></script>
193+
</span>
194+
195+
<!-- HelixUI custom element definitions -->
196+
<script src="cdn/path/to/helix-ui.js"></script>
197+
198+
<!-- load your application logic here -->
199+
<script src="domain/path/to/your/app.js"></script>
200+
</body>
201+
{% endcode %}
135202
</section>
136203
</section>
204+
205+
<section><!-- Bootstrap Theme -->
206+
<h2 class="hxSectionTitle" id="bootstrap-theme">Bootstrap Theme</h2>
207+
<div class="hxAlert hxAlert--warning">
208+
<div class="hxAlert__icon">
209+
<hx-icon type="exclamation-triangle"></hx-icon>
210+
</div>
211+
<div class="hxAlert__text">
212+
<span class="hxAlert__status">Warning</span>
213+
The Bootstrap theme <b>does not comply</b> to current Helix design specs.
214+
</div>
215+
</div>
216+
217+
<table class="hxTable hxTable--condensed">
218+
<thead>
219+
<tr>
220+
<th></th>
221+
<th>Development (unminified)</th>
222+
<th>Production (minified)</th>
223+
</tr>
224+
</thead>
225+
<tbody>
226+
<tr>
227+
<th>Helix Bootstrap Theme</th>
228+
<td>
229+
<a href="{{page.cdn}}/css/bootstrap.helix.css" target="_blank">
230+
<hx-icon type="external-link"></hx-icon>
231+
bootstrap.helix.css
232+
</a>
233+
</td>
234+
<td>N/A</td>
235+
</tr>
236+
</tbody>
237+
</table>
238+
</section>
137239
{% endblock %}

0 commit comments

Comments
 (0)