-
Notifications
You must be signed in to change notification settings - Fork 160
/
index.html
1671 lines (1667 loc) · 69.2 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
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
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>
Manifest for web application
</title>
<script src="//www.w3.org/Tools/respec/respec-w3c-common" class="remove">
</script>
<script class='remove'>
/**/
var respecConfig = {
specStatus: 'ED',
shortName: 'appmanifest',
subtitle: 'Living Document',
edDraftURI: 'http://w3c.github.io/manifest/',
previousMaturity: 'FPWD',
previousURI: 'http://www.w3.org/TR/2013/WD-appmanifest-20131217/',
editors: [{
name: 'Contributors list available on GitHub',
url:"https://github.com/w3c/manifest/graphs/contributors"
}],
wg: 'Web Applications (WebApps) Working Group',
wgURI: 'http://www.w3.org/2008/webapps/',
wgPublicList: 'public-webapps',
wgPatentURI: 'http://www.w3.org/2004/01/pp-impl/42538/status',
noLegacyStyle: true,
otherLinks: [{
key: 'Repository',
data: [{
value: 'We are on Github.',
href: 'https://github.com/w3c/manifest'
}, {
value: 'File a bug.',
href: 'https://github.com/w3c/manifest/issues'
}, {
value: 'Commit history.',
href: 'https://github.com/w3c/manifest/commits/gh-pages'
}, {
value: 'Mailing list.',
href: 'http://lists.w3.org/Archives/Public/public-webapps/'
}]
}, {
key: "Implementation status",
data: [{
value: "Gecko",
href: "https://bugzilla.mozilla.org/show_bug.cgi?id=997779"
}, {
value: "Blink",
href: "https://code.google.com/p/chromium/issues/detail?id=366145"
}]
}],
};
</script>
</head>
<body>
<section id='abstract'>
<p>
This specification defines a JSON-based manifest, which provides
developers with a centralized place to put metadata associated with a
web application. This includes, but is not limited to, the web
application's name, links to icons, as well as the preferred URL to
open when a user launches the web application. The manifest also allows
developers to declare a default orientation for their web application,
as well as providing the ability to set the display mode for the
application (e.g., in fullscreen).
</p>
<p>
Using this metadata, user agents can provide developers with means to
create user experiences that are more comparable to that of a native
application.
</p>
<p>
In addition, this specification defines the <code>manifest</code> link
type, which provides a declarative means for a document to be
associated with a manifest.
</p>
</section>
<section id="sotd">
<p>
Implementors need to be aware that this specification is extremely
unstable. <strong>Implementors who are not taking part in the
discussions will find the specification changing out from under them in
incompatible ways.</strong> Vendors interested in implementing this
specification before it eventually reaches the Candidate Recommendation
phase should <a href="https://github.com/w3c/manifest/issues">subscribe
to the repository on GitHub</a> and take part in the discussions.
</p>
</section>
<section class="informative">
<h2>
Usage Examples
</h2>
<p>
This section shows how developers can make use of the various features
of this specification.
</p>
<section class="informative">
<h3>
Example manifest
</h3>
<p>
The following shows a typical <a>manifest</a>.
</p>
<pre class="example highlight json" title="typical manifest">
{
"name": "Super Racer 2000",
"icons": [{
"src": "icon/lowres",
"sizes": "64x64",
"type": "image/webp"
}, {
"src": "icon/hd_small",
"sizes": "64x64"
}, {
"src": "icon/hd_hi",
"sizes": "128x128",
"density": "2"
}],
"start_url": "/start.html",
"display": "fullscreen",
"orientation": "landscape"
}
</pre>
</section>
<section class="informative">
<h3>
Using a <code>link</code> element to link to a manifest
</h3>
<p>
Example of using a <code>link</code> element to associate a website
with a <a>manifest</a>. The example also shows how to use [[!HTML]]'s
<code>link</code> and <code>meta</code> elements to give the web
application a fallback name and set of icons.
</p>
<pre class="example highlight html" title="linking to a manifest">
<!doctype>
<html>
<title>Store finder - search</title>
<!-- Startup configuration -->
<link rel="manifest" href="manifest.json">
<!-- Fallback application metadata for legacy browsers -->
<meta name="application-name" content="Store Finder">
<link rel="icon" sizes="16x16 32x32 48x48" href="lo_def.ico">
<link rel="icon" sizes="512x512" href="hi_def.png">
</pre>
</section>
</section>
<section>
<h2>
Use cases and requirements
</h2>
<p>
This document attempts to address the <cite><a href=
"http://w3c-webmob.github.io/installable-webapps/">Use Cases and
Requirements for Installable Web Apps</a></cite>.
</p>
</section>
<section>
<h2>
Common conventions and dependencies
</h2>
<p id="ecmascript-abstractop">
The <dfn><a href=
"http://people.mozilla.org/~jorendorff/es6-draft.html#sec-ordinary-object-internal-methods-and-internal-slots-getownproperty-p">
[[\GetOwnProperty]]</a></dfn> operation and the abstract operation
<dfn><a href=
"http://people.mozilla.org/~jorendorff/es6-draft.html#sec-hasownproperty">
hasOwnProperty</a></dfn>, <dfn title="parseFloat"><a href=
"http://people.mozilla.org/~jorendorff/es6-draft.html#sec-parsefloat-string">
parseFloat(string)</a></dfn> function, and the <a class="external"
href="http://people.mozilla.org/~jorendorff/es6-draft.html#sec-ecmascript-data-types-and-values">
<dfn>Type</dfn>(<var>x</var>)</a> notation are defined in
[[!ECMASCRIPT]].
</p>
<p>
When instructed to <dfn>Trim</dfn>(<var>x</var>), a user agent MUST
behave as if [[!ECMASCRIPT]]'s <a href=
"https://people.mozilla.org/~jorendorff/es6-draft.html#sec-string.prototype.trim">
String.prototype.trim()</a> function had been called on the string
<var>x</var>.
</p>
<p>
As the manifest uses the JSON format, this specification relies on the
types defined in [[!ECMA-404]] specification: namely <dfn title=
"json-object">object</dfn>, <dfn title="json-array">array</dfn>,
<dfn title="json-number">number</dfn>, <dfn title=
"json-string">string</dfn>, <code>true</code>, <code>false</code>, and
<code>null</code>. Strict type checking is not enforced by this
specification. Instead, each member's definition specifies the steps
required to process a particular member and what to do when a type does
not match what is expected.
</p>
</section>
<section>
<h2>
Display modes
</h2>
<p>
A <dfn>display mode</dfn> represents how developers would like the user
agent to present the web application to a user (e.g., in fullscreen).
Display modes correspond to user interface (UI) metaphors and
functionality in use on a given platform. The UI conventions of the
display modes are purely advisory and implementers are free to
interpret them how they best see fit.
</p>
<p>
Once a user agent applies a particular <a>display mode</a> to a web
application, it becomes the <dfn>default display mode</dfn> for the
<a href=
"http://www.whatwg.org/specs/web-apps/current-work/#top-level-browsing-context">
top-level browsing context</a> (i.e., it is used as the display mode
when the window is <a href=
"http://www.whatwg.org/specs/web-apps/current-work/#navigate">navigated</a>).
The user agent MAY override the <a>default display mode</a> for
security reasons (e.g., the <a href=
"http://www.whatwg.org/specs/web-apps/current-work/#top-level-browsing-context">
top-level browsing context</a> is <a href=
"http://www.whatwg.org/specs/web-apps/current-work/#navigate">navigated</a>
to another origin) and/or the user agent MAY provide the user with a
means of switching to another <a>display mode</a>.
</p>
<p>
When the <code>display</code> member is missing, or if there is no
valid <code>display</code> member, the user agent uses the
<code>browser</code> <a>display mode</a> as the <a>default display
mode</a>. As such, the user agent is REQUIRED to support the
<code>browser</code> <a>display mode</a>.
</p>
<p>
Each <a>display mode</a>, except <code>browser</code>, has a recursive
<dfn>fallback display mode</dfn>, which is the <a>display mode</a> that
the user agent can try to use if it doesn't support a particular
<a>display mode</a>. If the user agent does support a fallback display
mode, then it checks to see if it can use that display mode's fallback
display mode. This creates a fallback chain, with the <a>default
display mode</a> (<code>browser</code>) being the last item in the
chain.
</p>
<div class="example">
<p>
For example, Awesome Browser only supports the
<code>minimal-ui</code> and <code>browser</code> display modes, but
developer declares that she wants <code>fullscreen</code> in the
manifest. In this case, the user agent will first check if it
supports <code>fullscreen</code> (it doesn't), then fall back to
<code>standalone</code> (which it also doesn't support), and
ultimately fall back to <code>minimal-ui</code>.
</p>
</div>
<p>
The <dfn>display modes values</dfn> and their corresponding <a title=
"fallback display mode">fallback display modes</a> are as follows:
</p>
<dl>
<dt>
<dfn id="dm-fullscreen">fullscreen</dfn>
</dt>
<dd>
Opens the web application without any user agent chrome and takes up
the entirety of the available display area.
</dd>
<dd>
The <a>fallback display mode</a> for <code>fullscreen</code> is
<code>standalone</code>.
</dd>
<dt>
<dfn id="dm-standalone">standalone</dfn>
</dt>
<dd>
Opens the web application to look and feel like a standalone native
application. This can include the application having a different
window, its own icon in the application launcher, etc. In this mode,
the user agent will exclude UI elements for controlling navigation,
but can include other UI elements such as a status bar.
</dd>
<dd>
The <a>fallback display mode</a> for <code>standalone</code> is
<code>minimal-ui</code>.
</dd>
<dt>
<dfn id="dm-minimal-ui">minimal-ui</dfn>
</dt>
<dd>
This mode is similar to <a>fullscreen</a>, but provides the end-user
with some means to access a minimal set of UI elements for
controlling navigation (i.e., back, forward, reload, and perhaps some
way of viewing the document's address). A user agent can include
other platform specific UI elements, such as "share" and "print"
buttons or whatever is customary on the platform and user agent.
</dd>
<dd>
The <a>fallback display mode</a> for <code>minimal-ui</code> is
<code>browser</code>.
</dd>
<dt>
<dfn id="dm-browser">browser</dfn>
</dt>
<dd>
Opens the web application using the platform-specific convention for
opening hyperlinks in the user agent (e.g., in a browser tab or a new
window).
</dd>
<dd>
The <code>browser</code> <a>display mode</a> doesn't have a
<a>fallback display mode</a> (conforming user agents are required to
support the <code>browser</code> <a>display mode</a>).
</dd>
</dl>
<p class="note">
The <a>fullscreen</a> <a>display mode</a> is orthogonal to, and works
independently of, the [[FULLSCREEN]] API. The
<a><code>fullscreen</code></a> <a>display mode</a> affects the
fullscreen state of the browser window, while the [[FULLSCREEN]] API
operates on an element contained within the viewport. As such, a web
application can have its <a>display mode</a> set to
<a><code>fullscreen</code></a>, while
<code>document.fullScreenElement</code> returns <code>null</code>, and
<code>fullscreenEnabled</code> returns <code>false</code>.
</p>
</section>
<section>
<h2>
Manifest
</h2>
<p>
A <dfn>manifest</dfn> is a JSON document that contains startup
parameters and application defaults for when a web application is
launched. A manifest consists of a top-level <a href=
"#json-object">object</a> that contains zero or more members. Each of
the members are defined below, as well as how their values are
processed.
</p>
<section>
<h3>
Associating a resource with a manifest
</h3>
<p>
A resource is said to be <dfn>associated with a manifest</dfn> if the
resource representation, an HTML document, has a <a href=
"#linking"><code>manifest</code> link relationship</a>, or the
resource has a <a>well-known manifest</a>.
</p>
</section>
<section>
<h3>
Processing the manifest
</h3>
<p>
When instructed to <dfn>issue a developer warning</dfn>, the user
agent MAY report the conformance violation to the developer in a
user-agent-specific manner (e.g., report the problem in an error
console), or MAY ignore the error and do nothing.
</p>
<p>
When instructed to <dfn>ignore</dfn>, the user agent MUST act as if
whatever member or value caused the condition was absent from the
manifest document.
</p>
<p>
The following algorithm provides an <dfn>extension point</dfn>: other
specifications that add new members to the manifest are encouraged to
hook themselves into this specification at this point in the
algorithm.
</p>
<div class="note">
<p>
The <a>extension point</a> is meant to help avoid <a href=
"http://annevankesteren.nl/2014/02/monkey-patch">issues related to
monkey patching</a>.
</p>
</div>
<p>
The <dfn>steps for processing a manifest</dfn> are given by the
following algorithm. The algorithm takes a <var>text</var> string as
an argument, which represents a <a>manifest</a>, and a <var>manifest
URL</var> [[!URL]], which represents the location of the manifest,
and a <var>doc URL</var> [[!URL]]. The output from inputting an JSON
document into this algorithm is a <dfn>processed manifest</dfn>.
</p>
<ol>
<li>Let <var>parsed manifest</var> be an empty object.
</li>
<li>Let <var>manifest</var> be the result of <a href=
"https://people.mozilla.org/~jorendorff/es6-draft.html#sec-json.parse">
parsing</a> <var>text</var>. If <a href=
"https://people.mozilla.org/~jorendorff/es6-draft.html#sec-json.parse">
parsing</a> throws an error:
<ol>
<li>Issue a developer warning with any details pertaining to the
JSON parsing error.
</li>
<li>Set <var>manifest</var> to be the result of <a href=
"https://people.mozilla.com/~jorendorff/es6-draft.html#sec-15.12.2">
parsing</a> the string <code>"{}"</code>.
</li>
</ol>
</li>
<li>
<a>Extension point</a>: process any proprietary and/or other
supported members at this point in the algorithm.
</li>
<li>Let <var>start URL</var> of <var>parsed manifest</var> be the
result of running the <a>steps for processing the
<code>start_url</code> member</a> with <var>manifest URL</var> and
<var>doc URL</var>.
</li>
<li>If <var>start URL</var> of <var>parsed manifest</var> is
<code>undefined</code>, set <var>start URL</var> of <var>parsed
manifest</var> to be <var>doc URL</var><a href=
"http://www.whatwg.org/specs/web-apps/current-work/#the-document's-address"></a>.
</li>
<li>Let <var>display mode</var> of <var>parsed manifest</var> be the
result of running the <a>steps for processing the
<code>display</code> member</a> with <var>manifest</var> as the
argument.
</li>
<li>Let <var>orientation</var> of <var>parsed manifest</var> be the
result of running the <a>steps for processing the
<code>orientation</code> member</a> with <var>manifest</var> and
<var>display mode</var> as arguments.
</li>
<li>Let <var>name</var> of <var>parsed manifest</var> be the result
of running the <a>steps for processing the <code>name</code>
member</a>.
</li>
<li>Let <var>short name</var> of <var>parsed manifest</var> be the
result of running the <a>steps for processing the
<code>short_name</code> member</a>.
</li>
<li>Let <var>icons</var> of <var>parsed manifest</var> be the result
of running the <a>steps for processing the <code>icons</code>
member</a>.
</li>
<li>Return <var>parsed manifest</var>.
</li>
</ol>
</section>
<section>
<h3>
Updating the manifest
</h3>
<p>
A user agent MAY periodically check if the contents of a manifest has
been modified (e.g., by honoring HTTP cache directives associated
with the manifest or by checking for updates after the web
application has been launched). In the event that the members of the
manifest have been updated, as determined by running the <a>steps for
processing a manifest</a> and seeing if anything has changed, the
user agent MAY update the metadata corresponding to the web
application (e.g., by updating or discarding the name, icons, or
whatever other members have been changed).
</p>
<p>
In addition, even if the manifest has not been modified, the user
agents MAY periodically check if resources referenced from a manifest
(e.g., the icons) have been modified by honoring HTTP cache
directives. If any resources have been modified, the user agent MAY
replace any stale resources.
</p>
<p>
To avoid one application masquerading as another, it is RECOMMENDED
that users be made aware of any such updates using implementation or
platform specific conventions.
</p>
</section>
<section>
<h3>
<code title="">name</code> member
</h3>
<p>
The <dfn id="member-name"><code>name</code></dfn> member is a
<a title="json-string">string</a> that represents the name of the web
application as it is usually displayed to the user (e.g., amongst a
list of other applications, or as a label for an icon).
</p>
<p class="note">
For all intents and purposes, the <code><a href=
"#member-name">name</a></code> member is functionally equivalent to
having a <code><a href=
"http://www.whatwg.org/specs/web-apps/current-work/#the-meta-element">
meta</a></code> element whose <a href=
"http://www.whatwg.org/specs/web-apps/current-work/#attr-meta-name">name</a>
attribute is <a href=
"http://www.whatwg.org/specs/web-apps/current-work/#meta-application-name">
<code>application-name</code></a> in a [[!HTML]] document. In cases
where no suitable name can be derived from processing a manifest,
[[!HTML]]'s <a href=
"http://www.whatwg.org/specs/web-apps/current-work/#meta-application-name">
application-name</a> or the <code><a href=
"http://www.whatwg.org/specs/web-apps/current-work/#the-title-element">
title</a></code> element serve as suitable fallbacks.
</p>
<p>
The <dfn>steps for processing the name member</dfn> is given by the
following algorithm. The algorithm takes a <var>manifest</var> as an
argument. This algorithm returns a string or <code>undefined</code>.
</p>
<ol>
<li>Let <var>value</var> be the result of calling the
<a>[[\GetOwnProperty]]</a> internal method of <var>manifest</var>
with argument "<code>name</code>".
</li>
<li>If <a>Type</a>(<var>value</var>) is not "string":
<ol>
<li>If <a>Type</a>(<var>value</var>) is not "undefined",
optionally <a>issue a developer warning</a> that the type is not
supported.
</li>
<li>Return <code>undefined</code>.
</li>
</ol>
</li>
<li>Otherwise, <a>Trim</a>(<var>value</var>) and return the result.
</li>
</ol>
</section>
<section>
<h3>
<code title="">short_name</code> member
</h3>
<p>
The <dfn id="member-short_name"><code>short_name</code></dfn> member
is a <a title="json-string">string</a> that represents a short
version of the name of the web application. It is intended to be used
where there is insufficient space to display the full name of the web
application.
</p>
<p>
The <dfn>steps for processing the short name member</dfn> is given by
the following algorithm. The algorithm takes a <var>manifest</var> as
an argument. This algorithm returns a string or
<code>undefined</code>.
</p>
<ol>
<li>Let <var>value</var> be the result of calling the
<a>[[\GetOwnProperty]]</a> internal method of <var>manifest</var>
with argument "short_<code>name</code>".
</li>
<li>If <a>Type</a>(<var>value</var>) is not "string":
<ol>
<li>If <a>Type</a>(<var>value</var>) is not "undefined",
optionally <a>issue a developer warning</a> that the type is not
supported.
</li>
<li>Return <code>undefined</code>.
</li>
</ol>
</li>
<li>Otherwise, <a>Trim</a>(<var>value</var>) and return the result.
</li>
</ol>
</section>
<section>
<h3>
<code title="">icons</code> member
</h3>
<p>
The <dfn id="member-icons"><code>icons</code></dfn> member is an
<a title="json-array">array</a> of <a title="icon object">icon
objects</a> that can serve as iconic representations of the web
application in various contexts. For example, they can be used to
represent the web application amongst a list of other applications,
or to integrate the web application with an <abbr title=
"operating system">OS</abbr>'s task switcher and/or system
preferences.
</p>
<p class="note">
If no icons are listed in the manifest (or none of them are found to
be suitable during processing), it is RECOMMENDED that the user agent
fall back to using any icons found in the <code>Document</code> of
the <a href=
"http://www.whatwg.org/specs/web-apps/current-work/#top-level-browsing-context">
top-level browsing context</a>. For example, an <a href=
"http://www.whatwg.org/specs/web-apps/current-work/#rel-icon">icon
link type</a> and/or a <code>favicon.ico</code> can serve as suitable
fallbacks.
</p>
<p>
The <dfn>steps for processing the <code>icons</code> member</dfn> are
given by the following algorithm. The algorithm takes a manifest, and
a <a href="http://url.spec.whatwg.org/#concept-url">URL</a>
<var>manifest URL</var>, which is the URL from which the
<var>manifest</var> was fetched. This algorithm will return a list of
icons objects <var>icons</var>, which can be empty.
</p>
<ol>
<li>Let <var>icons</var> be an empty list.
</li>
<li>Let <var>unprocessed icons</var> be the result of calling the <a>
[[\GetOwnProperty]]</a> internal method of <var>manifest</var> with
argument "<code>icons</code>".
</li>
<li>If <var>unprocessed icons</var> is an <a title=
"json-array">array</a>, then:
<ol>
<li>From unprocessed icons, filter out any <var>item</var> where
<a>HasOwnProperty</a>(item,"src") returns <code>false</code>.
</li>
<li>For each <var>potential icon</var> in the array:
<ol>
<li>Let <var>src</var> be the result of running the <a>steps
for processing the <code>src</code> member of an icon</a>
with <var>potential icon</var> and <var>manifest URL</var>.
</li>
<li>If <var>src</var> is <code>undefined</code>, move onto
the next item in <var>icons</var> (if any are left).
</li>
<li>Otherwise, let <var>icon</var> be an object with
properties <code>src</code>, <code>type</code>,
<code>sizes</code>, and <code>density</code>. All properties
initially set to <code>undefined</code>.
</li>
<li>Set <var>icon</var>'s <code>src</code> property to be
<var>src</var>.
</li>
<li>Let <var>type</var> be the result of running the <a>steps
for processing the <code>type</code> member of an icon</a>
passing <var>potential icon</var>.
</li>
<li>If <var>type</var> is not <code>undefined</code>, set
<var>icon</var>'s <code>type</code> property to be
<var>type</var>.
</li>
<li>Let <var>sizes</var> be the list that result from running
the <a>steps for processing a <code>sizes</code> member of an
icon</a> passing <var>potential icon</var>.
</li>
<li>If <var>sizes</var> is not <code>undefined</code>, set
<var>icon</var>'s <code>sizes</code> property to be
<var>sizes</var>.
</li>
<li>Let <var>density</var> be the result from running the <a>
steps for processing a <code>density</code> member of an
icon</a> are given by the passing <var>potential
icon</var>.
</li>
<li>If <var>density</var> is not <code>undefined</code>, set
<var>icon</var>'s <code>density</code> property to be
<var>value</var>.
</li>
<li>Append <var>icon</var> to <var>icons</var>.
</li>
</ol>
</li>
</ol>
</li>
<li>Otherwise, if <var>unprocessed icons</var> is not an <a title=
"json-array">array</a>:
<ol>
<li>
<a>Issue a developer warning</a> that the type is not
supported.
</li>
</ol>
</li>
<li>Return <var>icons</var>.
</li>
</ol>
<p>
If there are multiple equally appropriate icons in <var>icons</var>,
a user agent MUST use the last one declared in order at the time that
the user agent collected the list of <var>icons</var>. If the user
agent tries to use an icon but that icon is determined, upon closer
examination, to in fact be inappropriate (e.g. because its content
type is unsupported), then the user agent MUST try the
next-most-appropriate icon as determined by examining the <a title=
"icon object">icon object's</a> members.
</p>
</section>
<section>
<h3>
<code>display</code> member
</h3>
<p>
The <dfn id="member-display"><code>display</code></dfn> member is a
<a href="#json-string">string</a>, whose value is one of <a>display
modes values</a>. The item represents the developer's preferred
<a>display mode</a> for the web application. When the member is
missing or erroneous, the user agent MUST use the <a>fallback display
mode</a>.
</p>
<p>
The <dfn>steps for processing the <code>display</code> member</dfn>
are given by the following algorithm. The algorithm takes a manifest
<var>manifest</var> as an argument, and returns a string.
</p>
<ol>
<li>Let <var>value</var> be the result of calling the
<a>[[\GetOwnProperty]]</a> internal method of <var>manifest</var>
passing "<code>display</code>" as the argument.
</li>
<li>If <a>Type</a>(<var>value</var>) is not "string" or
<var>value</var> is not part of the <a>display modes values</a>:
<ol>
<li>If <a>Type</a>(<var>value</var>) is not "undefined", <a>issue
a developer warning</a> that the type is unsupported.
</li>
<li>Return the <a>fallback display mode</a>'s value.
</li>
</ol>
</li>
<li>Otherwise, <a>Trim</a>(<var>value</var>) and set <var>value</var>
to be the result.
</li>
<li>If <var>value</var> is not a display mode that the user agent
supports, set <var>value</var> to <var>value</var>'s <a>fallback
display mode</a> and rerun this step.
</li>
<li>Return <var>value</var>.
</li>
</ol>
</section>
<section>
<h3>
<code>orientation</code> member
</h3>
<p>
The <dfn id="member-orientation"><code>orientation</code></dfn>
member is a <a href="#json-string">string</a> that serves as the
<a href=
"https://w3c.github.io/screen-orientation/#dfn-default-orientation">default
orientation</a> for all <a href=
"http://www.whatwg.org/specs/web-apps/current-work/#top-level-browsing-context">
top-level browsing contexts</a> of the web application. The possible
values is one of the <a href=
"https://w3c.github.io/screen-orientation/#idl-def-OrientationLockType">
OrientationLockType</a> enum defined in [[!SCREEN-ORIENTATION]].
</p>
<p>
If the user agent honors the value of the <code>orientation</code>
member as the <a href=
"https://w3c.github.io/screen-orientation/#dfn-default-orientation">default
orientation</a>, then that serves as the <a href=
"https://w3c.github.io/screen-orientation/#dfn-default-orientation">default
orientation</a> for the life of the web application (unless
overridden by some other means at runtime). This means that the user
agent MUST return the orientation to the <a href=
"https://w3c.github.io/screen-orientation/#dfn-default-orientation">default
orientation</a> any time the orientation is unlocked
[[!SCREEN-ORIENTATION]] or the <a href=
"http://www.whatwg.org/specs/web-apps/current-work/#top-level-browsing-context">
top-level browsing context</a> is <a href=
"http://www.whatwg.org/specs/web-apps/current-work/#navigate">navigated</a>.
</p>
<p>
Although the specification relies on the [[!SCREEN-ORIENTATION]]'s
<a href=
"https://w3c.github.io/screen-orientation/#idl-def-OrientationLockType">
OrientationLockType</a>, it is OPTIONAL for a user agent to implement
the [[!SCREEN-ORIENTATION]] API. Supporting the
[[!SCREEN-ORIENTATION]] API is, of course, RECOMMENDED.
</p>
<p class="note">
Once the web application is running, other means can change the
orientation of a <a href=
"http://www.whatwg.org/specs/web-apps/current-work/#top-level-browsing-context">
top-level browsing context</a> (such as via [[!SCREEN-ORIENTATION]]
API).
</p>
<p>
The <dfn>steps for processing the <code>orientation</code>
member</dfn> are given by the following algorithm. The algorithm
takes a <a>manifest</a> <var>manifest</var> and display mode
<var>display mode</var> as an argument, and returns a string.
</p>
<ol>
<li>Let <var>value</var> be the result of calling the
<a>[[\GetOwnProperty]]</a> internal method of <var>manifest</var>
with argument "<code>orientation</code>".
</li>
<li>If <a>Type</a>(<var>value</var>) is not "string":
<ol>
<li>If <a>Type</a>(<var>value</var>) is not "undefined", <a>issue
a developer warning</a> that the type is not supported.
</li>
<li>Return the empty string.
</li>
</ol>
</li>
<li>Otherwise, <a>Trim</a>(<var>value</var>) and set <var>value</var>
to be the result.
</li>
<li>If <var>value</var> is unsupported by the user agent, or the
<var>value</var> cannot be used together with <var>display
mode:</var>
<ol>
<li>
<a>Issue a developer warning</a>.
</li>
<li>Return the empty string.
</li>
</ol>
</li>
<li>Return <var>value</var>.
</li>
</ol>
</section>
<section>
<h3>
<code>start_url</code> member
</h3>
<p>
The <dfn title="member-url"><code>start_url</code></dfn> member is a
<a title="json-string">string</a> that represents the <a href=
"http://url.spec.whatwg.org/#concept-url">URL</a> that the developer
would prefer the user agent <a href=
"http://www.w3.org/html/wg/drafts/html/master/single-page.html#browsers">
load</a> when the user launches the web application (e.g., when the
user clicks on the icon of the web application from a device's
application menu or homescreen).
</p>
<p>
The <a title="member-url"><code>start_url</code></a> member is purely
advisory, and a user agent MAY <a>ignore</a> it or provide the
end-user the choice not to make use of it. A user agent MAY also
allow the end-user to modify the URL when, for instance, a bookmark
for the web application is being create or any time thereafter.
</p>
<p>
The <dfn>steps for processing the <code>start_url</code> member</dfn>
are given by the following algorithm. The algorithm takes a
<a>manifest</a> <var>manifest</var>, a <a href=
"http://url.spec.whatwg.org/#concept-url">URL</a> <var>manifest
URL</var>, and a <a href=
"http://url.spec.whatwg.org/#concept-url">URL</a> <var>origin
URL</var>. This algorithm returns a [[!URL] or
<code>undefined</code>.
</p>
<ol>
<li>Let <var>value</var> be the result of calling the
<a>[[\GetOwnProperty]]</a> internal method of the <var>manifest</var>
with argument "<code>start_url</code>".
</li>
<li>Let <var>type</var> be <a>Type</a>(<var>value</var>).
</li>
<li>If <var>type</var> is not "string" or <var>value</var> is the
empty string, then:
<ol>
<li>If <var>type</var> is not "<code>undefined</code>", issue a
developer warning that the type is unsupported.
</li>
<li>Return <code>undefined</code>.
</li>
</ol>
</li>
<li>Let <var>url</var> be the result of <a href=
"http://url.spec.whatwg.org/#parsing">parsing</a> <var>value</var>
using <var>manifest URL</var> as the base URL.
</li>
<li>If <var>url</var> is failure, return <code>undefined</code>.
</li>
<li>If url is not <a href=
"http://www.whatwg.org/specs/web-apps/current-work/#same-origin">same
origin</a> as document URL:
<ol>
<li>
<a>Issue a developer warning</a> that the
<code>start_url</code> needs to be <a href=
"http://www.whatwg.org/specs/web-apps/current-work/#same-origin">
same-origin</a> as the document.
</li>
<li>Return <var>undefined</var>.
</li>
</ol>
</li>
<li>Otherwise, return <var>url</var>.
</li>
</ol>
</section>
<section id="linking">
<h3>
Linking to a manifest
</h3>
<p>
The <code>manifest</code> keyword can be used with a [[!HTML]]
<a href=
"http://www.whatwg.org/specs/web-apps/current-work/#the-link-element">
link</a> element. This keyword creates an <a href=
"http://www.whatwg.org/specs/web-apps/current-work/#external-resource-link"
title="external resource link">external resource link</a>.
</p>
<table border="1">
<tr>
<th rowspan="2">
Link type
</th>
<th colspan="2">
Effect on...
</th>
<th rowspan="2">
Brief description
</th>
</tr>
<tr>
<th>
<code><a href="#the-link-element">link</a></code>
</th>
<th>
<code><a href="#the-a-element">a</a></code> and <code><a href=
"#the-area-element">area</a></code>
</th>
</tr>
<tr>
<td>
<code><dfn title="rel-manifest" id=
"rel-manifest">manifest</dfn></code>
</td>
<td>
<a href=
"http://www.whatwg.org/specs/web-apps/current-work/#external-resource-link"
title="external resource link">External Resource</a>
</td>
<td>
not allowed
</td>
<td>
Imports or links to a <a>manifest</a>.
</td>
</tr>
</table>
<p>
The <a>media type for a manifest</a> serves as the default media type
for resources associated with the <code><a href=
"#rel-manifest">manifest</a></code> <a href=
"http://www.whatwg.org/specs/web-apps/current-work/#linkTypes">link
type</a>.
</p>
<p class="note">
In cases where more than one <a href=
"http://www.whatwg.org/specs/web-apps/current-work/#the-link-element">
<code>link</code></a> element with a <code>manifest</code> link type
appears in a <code>Document</code>, the user agent uses the first
link element in tree order and ignores all subsequent <a href=
"http://www.whatwg.org/specs/web-apps/current-work/#the-link-element">
<code>link</code></a> elements with a <code>manifest</code> link type
(even if the first element was erroneous). See the <a>steps for
obtaining a manifest</a>.
</p>
<p>
To obtain a manifest, the user agent MUST run the <a>steps for
obtaining a manifest</a>. The appropriate time to obtain the manifest
is left up to implementations. A user agent MAY opt to delay fetching
a manifest until after the document and its other resources have been
fully loaded (i.e., to not delay the availability of content and
scripts required by the <code>document</code>).
</p>
<p>
A <a>manifest</a> is obtained and applied regardless of the <a href=
"http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#attr-link-media">
<code>media</code></a> attribute of the <a href=
"http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#the-link-element">
<code>link</code></a> matches the environment or not.
</p>
</section>
<section>
<h3>
Content security policy
</h3>
<p class="issue">
The `<code>manifest-src</code>` hasn't yet been added to the CSP
spec. However, a <a href=
"https://github.com/w3c/webappsec/issues/29">feature request has been
filed</a> and accepted by the Editor.
</p>
<p>
Just like [[!HTML]] documents, a manifest can have an associated
[[!CSP]] policy. The manifest's policy controls, for example, where
resources like <a title="icon object">icons</a> can be loaded from
(via the <code><a href=
"https://w3c.github.io/webappsec/specs/content-security-policy/#directive-img-src">
img-src</a></code> directive).
</p>
<p>
A user agent MUST treat the a manifest's policy as independent of any
policy applied to [[!HTML]] document. A manifest's [[!CSP]] policy
can only be delivered over HTTP.
</p>
<div class="example">
<figure>
<img src="images/indipendent_policies.svg" width="224" height="332"
alt="">
<figcaption>
The [[!CSP]] policy applied to a [[!HTML]] document is
independent from, and does not interact with, the policy applied
to the manifest. Where are manifest can be loaded from is
controlled by the HTML's document's CSP policy.
</figcaption>
</figure>
</div>
<p>
For [[!HTML]] document, [[!CSP]]'s <code>manifest-src</code>
directive controls the sources from which a [[!HTML]] document can
load a manifest from.
</p>
<div class="example">
<figure class="exaple">
<img src="images/manifest-src-directive.svg" width="704" height=