-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathindex.html
More file actions
399 lines (377 loc) · 17.3 KB
/
Copy pathindex.html
File metadata and controls
399 lines (377 loc) · 17.3 KB
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
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
<html>
<head>
<title>responsively.js</title>
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Condiment:400,300,300italic,400italic,700,700italic|Gentium+Basic:400italic,700italic|Buenard:400,700&|Inconsolata;subset=latin,latin-ext" type="text/css">
<link rel="stylesheet" href="styles.css">
</head>
<body>
<div class="main header">
<h1>responsively.js</h1>
</div>
<div class="main">
<div>
<h2>what</h2>
<p>
<span class="rjs">responsively.js</span> is a small, open-source JavaScript micro-library designed to help solve responsive design problems.
</p>
<p>
It is designed to work well with sites that use client-side templates (handlebars.js, mustache, ...). It is <i>not</i> intended to replace
more traditional responsive design techniques (media queries, grids, ...) -- it should be used as a tool to solve specific responsive
design problems that are not easily handled using traditional techniques alone.
</p>
<p>
<span class="rjs">responsively.js</span> commonly can be helpful in two situations:
<ol>
<li>
<b>When content needs to be displayed differently based on the <i>content dimensions</i> rather than <i>device dimensions</i>.</b>
<br>
For example, content adjacent to abnormally large content might need to be displayed differently so that both pieces of content can still fit next to each other.
</li>
<li>
<b>Continuous device sizes.</b>
<br>
Unlike media queries, which typically have specific resolution breakpoints, <span class="rjs">responsively.js</span> will apply rules progressively when the content does not fit.
</li>
</ol>
</p>
</div>
<div>
<h2>download</h2>
<p>
From <b>Git</b>:
<span class="cmd">git clone git://github.com/responsively/responsivelyjs.git</span>
</p>
<p>
From <b>Bower</b>:
<span class="cmd">bower install responsively</span>
</p>
</div>
<div>
<h2>source</h2>
<span class="rjs">responsively.js</span> is maintained on Github at:
<p>
<a href="https://github.com/responsively/responsivelyjs" class="url">https://github.com/responsively/responsivelyjs</a>
</p>
</div>
<div>
<h2>usage</h2>
<h3>modules</h3>
<p>
<span class="rjs">responsively.js</span> supports AMD-style modules. If not used as an AMD module, it will expose a <span class="js">responsively</span> variable on the global window object.
</p>
<h3><span class="js">responsively</span> and <span class="js">renderer</span> objects</h3>
<p>
<span class="js">responsively</span> is a singleton function object which is invoked with a single <i>options</i> parameter. This returns a <span class="js">renderer</span> instance which has the following properties:
<ul>
<li>
<span class="js">render()</span>
<br>
This causes the <span class="js">renderer</span> to execute and process its rules.
</li>
<li>
<span class="js">update()</span>
<br>
This updates the DOM that <span class="js">renderer</span> is managing in-place. This is useful when a region of the screen needs to be dynamically updated and re-fit.
</li>
<li>
<span class="js">level</span>
<br>
This returns the current level that the <span class="js">renderer</span> has rendered to. This can be used to determine if something needs to be rendered in another way because it couldn't
fit into this <span class="js">renderer</span>'s parent element. For example, if you remove a "hints" element at level 2, and the <span class="renderer">renderer</span> is at level 2, you know that
the "hints" element has been removed and might need to be displayed elsewhere on the page.
</li>
</ul>
</p>
<h3><span class="js">responsively</span> options</h3>
<p>
The <i>options</i> object has the following options:
<ul>
<li>
<span class="js">parent<sub>string (selector) or jQuery object</sub></span>
<br>
This is the root element that is to be rendered.
</li>
<li>
<span class="js">constrain<sub>string (selector), <i>optional</i></sub></span>
<br>
Normally <span class="rjs">responsively.js</span> attempts to constrain to the height and width of the parent element. If <span class="js">constrain</span> is specified, it will constrain to the height and width of a
element matched by the <span class="js">constrain</span> selector. This selector is relative to <span class="js">parent</span>.
</li>
<li>
<span class="js">height<sub>integer (pixels), <i>optional</i></sub></span>
<br>
Responsively will keep applying levels until the height of the <span class="js">parent</span> (or <span class="js">constrain</span> element, if specified) is less than or equal to the
specified height. This option is useful if the <span class="js">parent</span> / <span class="js">constrain</span> element do not have a fixed height.
</li>
<li>
<span class="js">inner<sub>string (html), <i>optional</i></sub></span>
<br>
The parent's inner HTML will be set to this string. The string is typically the output of a template.
</li>
<li>
<span class="js">outer<sub>string (html), <i>optional</i></sub></span>
<br>
The parent's outer HTML will be set to this string. The string is typically the output of a template. If the string is set to <span class="js">null</span>, then the outer element will
be <i>removed</i> from the DOM. If both <span class="js">inner</span> and <span class="js">outer</span> are both specified, <span class="js">outer</span> is applied first, then
<span class="js">inner</span>.
</li>
<li>
<span class="js">menu<sub>object (menu options)</sub></span>
<br>
This is an object which defines a top-level menu. The menu is drawn using <a href="http://getbootstrap.com/components/#dropdowns">Twitter Bootstrap dropdown</a> conventions:
<ul>
<li>
<span class="js">a<sub>string (selector), <i>required</i></sub></span>
<br>
The menu will be rendered inside the element that this selector refers to. This selector is relative to <span class="js">parent</span>.
</li>
<li>
<span class="js">overflow<sub>object (overflow options)</sub></span>
<br>
This is an object which defines an overflow menu. <span class="rjs">responsively.js</span> will <i>progressively</i> slide menu options into the overflow dropdown menu if there is not enough room to
display all of the top-level menu options at one time. This is similar to how if you resize a default Twitter Bootstrap site down to a small size, it will move all of the
top-level menu items into an overflow dropdown. <span class="rjs">responsively.js</span> enhances this behavior by progressively migrating menu items into the dropdown -- no more "all or nothing".
<span class="rjs">responsively.js</span> also allows top-level menus to degrade to showing only icons instead of icons & labels as well.
<ul>
<li>
<span class="js">limit<sub>int</sub></span>
<br>
This specifies the maximum number of options which should be displayed on the top-level menu before moving options to the overflow menu.
</li>
<li>
All standard <a href="#menuOptions">menu item</a> options are also available. These define the appearance of the top-level overflow menu item itself.
</li>
</ul>
</li>
<li>
<span class="js">items<sub>array (<span class="js">'-'</span>, <span class="js">'|'</span>, and <i>menu item options</i>)</sub></span>
<br>
This is an array which contains a list of top-level menu items to display. A <span class="js">'-'</span> means to insert a menu separator while a
<span class="js">'|'</span> specifies that any following options should be forced into the overflow dropdown menu. An object means that it is
a menu item <i>options</i> object:
<ul>
<li>
<span class="js">hide<sub>boolean, <i>optional</i></span>
<br>
The menu item will not be rendered if this is set.
</li>
<li>
<span class="js">element<sub>html tag name, <i>optional</i></span>
<br>
Each menu item will be wrapped in the element specified. It defaults to <span class="js">'li'</span>. If you would like no wrapping element to be created,
specify <span class="js">null</span> or an empty string.
</li>
<li>
<span class="js">label<sub>string, <i>optional</i></span>
<br>
The label for the menu item. A menu item should have either a label, icon, or label and icon defined.
</li>
<li>
<span class="js">icon<sub>string, <i>optional</i></span>
<br>
If specified, this should be a set of classes for an icon to be added to the menu item. For example, <span class="js">'glyphicon glyphicon-search'</span>
(Glyphicons search icon) or <span class="js">'fa fa-calendar'</span> (Font Awesome calendar icon).
</li>
<li>
<span class="js">href<sub>url, <i>optional</i></span>
<br>
This specifies the <span class="js">href</span> for the menu item link.
</li>
<li>
<span class="js">target<sub>url, <i>optional</i></span>
<br>
This specifies the <span class="js">target</span> for the menu item link. Menu items default to no target.
</li>
<li>
<span class="js">classes<sub>string, <i>optional</i></span>
<br>
This specifies any extra classes to be added to the menu item's <span class="js">class</span> attribute.
</li>
<li>
<span class="js">style<sub>string, <i>optional</i></span>
<br>
This specifies the <span class="js">style</span> attribute for the menu item.
</li>
<li>
<span class="js">extra<sub>string, <i>optional</i></span>
<br>
This allows you to add arbitrary HTML to the menu item opening tag. For example, to add "data-" or "ng-" attributes.
</li>
</ul>
</li>
</ul>
</li>
<li>
<span class="js">rules<sub>array (rule options)</sub></span>
<br>
This is an array which contains a list of rules to progressively apply. Each rule is its own <i>options</i> object:
<ul>
<li>
<span class="js">when<sub>boolean, <i>optional</i></span>
<br>
If this option is present and evalutes to false, this rule will be skipped. Typically <span class="js">when</span> will be a function that returns a boolean.
</li>
<li>
<span class="js">level<sub>integer (level), <i>optional</i></span>
</li>
<li>
<span class="js">a<sub>string (selector), <i>required by <span class="js">inner</span>, <span class="js">outer</span>, <span class="js">css</span>, <span class="js">addClass</span>, <span class="js">removeClass</span>, and <span class="js">hide</span></i></sub></span>
<br>
This sets the anchor for this rule to the specified selector. This selector is relative to <span class="js">parent</span>.
</li>
<li>
<span class="js">fn<sub>function, <i>optional</i></span>
<br>
This function is simply evaluated whenever this rule triggers. The return value is not used.
</li>
<li>
<span class="js">inner<sub>string (html), <i>optional</i></sub></span>
<br>
The anchor's inner HTML will be set to this string. The string is typically the output of a template.
</li>
<li>
<span class="js">outer<sub>string (html), <i>optional</i></sub></span>
<br>
The anchor's outer HTML will be set to this string. The string is typically the output of a template. If the string is set to <span class="js">null</span>, then the outer element will
be <i>removed</i> from the DOM. If both <span class="js">inner</span> and <span class="js">outer</span> are both specified, <span class="js">outer</span> is applied first, then
<span class="js">inner</span>.
</li>
<li>
<span class="js">css<sub>object (css properties), <i>optional</i></sub></span>
<br>
The given CSS properties will be applied to the anchor. The css properties should be a JSON object containing <i>css property name</i>: <i>css property value</i> bindings.
</li>
<li>
<span class="js">addClass<sub>string (css class name), <i>optional</i></sub></span>
<br>
The given CSS class properties will be added to the anchor.
</li>
<li>
<span class="js">removeClass<sub>string (css class name), <i>optional</i></sub></span>
<br>
The given CSS class properties will be removed from the anchor.
</li>
<li>
<span class="js">hide<sub>boolean, <i>optional</i></span>
<br>
The element <span class="js">a</span> will be hidden (<span class="js">display: none</span>).
</li>
<li>
<span class="js">menuLimit<sub>int, <i>optional</i></span>
<br>
This changes the maximum number of menu items which will be shown on the top-level menu before overflowing to the overflow dropdown.
</li>
<li>
<span class="js">menuIcons<sub>boolean, <i>optional</i></span>
<br>
If set, this forces menu items to drop the labels and only show menu icons.
</li>
</ul>
</li>
</ul>
</p>
<p>
<i>Note:</i> All options can also be functions. If a function is found, it will be invoked and the return value of the function will be used as the final value.
</p>
<h3>how it works</h3>
<p>
<span class="rjs">responsively.js</span> first renders the parent <span class="js">outer</span> and <span class="js">inner</span> properties (if present). It then executes all level 0 rules in the
<span class="js">rules</span> array.
</p>
<p>
If the content does not fit, it will then keep moving up levels and applying rules at that level until the content fits or it runs out of levels.
</p>
<p>
Rules should be written to gradually remove and/or rewrite content so that the content will fit as size becomes more constrained (either due to smaller devices
or larger content elements).
</p>
<p>
This rendering is done effectively "desktop-first" because this ensures that the algorithm never needs to backtrack. The rendering is done off-screen to increase performance and
reduce screen flicker. Possibly in the future render decisions can be cached to speed rendering further.
</p>
<p>
Multiple <span class="js">renderer</span>s can be used on the same page to manage different elements.
</p>
<h3>dependencies</h3>
<p>
<span class="rjs">responsively.js</span> depends on jQuery 1.9 or later.
</p>
</div>
<div>
<h2>example</h2>
<pre>
responsively({
<b>parent</b>: '.banner',
<b>inner</b>: template( 'bannerTemplate' ),
<b>menu</b>: {
<b>a</b>: '#menuPlaceholder', <i>// menuPlaceholder should exist inside the output of template( 'bannerTemplate' ) in this example</i>
<b>overflow</b>: {
<b>label</b>: 'More',
<b>icon</b>: 'fa fa-wrench'
},
<b>items</b>: [
{
<b>label</b>: 'Users',
<b>href</b>: '#users',
<b>icon</b>: 'fa fa-user'
},
{
<b>label</b>: 'Document',
<b>href</b>: '#documents',
<b>icon</b>: 'fa fa-file'
},
{
<b>label</b>: 'Help',
<b>href</b>: '#help',
<b>icon</b>: 'fa fa-help'
}
]
},
<b>rules</b>: [
{
<i>// this will be called on the initial render, since it has no level, it is level 0. Level 0 is always called.</i>
<b>fn</b>: function() {
view.initControls();
}
},
{
<i>// remove hints if we are out of room</i>
<b>level</b>: 1,
<b>a</b>: '.hints',
<b>hide</b>: true
},
{
<b>level</b>: 1, <i>// this will be applied at the same time the preceding rule is, since they have the same level</i>
<b>fn</b>: function() {
...
}
},
{
<b>level</b>: 2,
<b>a</b>: '.saveBtn',
<b>inner</b>: function() { return template( 'labellessSaveBtn' ); },
<b>menuIcons</b>: true
},
{
<b>level</b>: 3,
<b>a</b>: '.saveBtn',
<b>css</b>: {
'font-size': '12px'
}
}
]
}).render();
</pre>
</div>
<div>
<h2>license</h2>
<span class="rjs">responsively.js</span> is licensed under the <a href="license.html">MIT License</a>.
</div>
<div>
<h2>contribute</h2>
<p>Feedback and pull requests are welcome!</p>
<p><a href="https://github.com/responsively/responsivelyjs/issues">Submit Feedback or Bugs</a></p>
</div>
</div>
</body>
</html>