Skip to content

Commit a9f58a4

Browse files
jpmedleyjpmedley
authored
Improve documentation for NDEFRecord (#7837)
1 parent 1b6da8a commit a9f58a4

File tree

9 files changed

+188
-76
lines changed

9 files changed

+188
-76
lines changed

‎files/en-us/web/api/ndefrecord/data/index.html

+23-6
Original file line numberDiff line numberDiff line change
@@ -10,20 +10,37 @@
1010
<p>{{securecontext_header}}{{SeeCompatTable}}{{APIRef()}}</p>
1111

1212
<p class="summary">The <strong><code>data</code></strong>
13-
property of the {{DOMxRef("NDEFRecord")}} interface is {{jsxref("DataView")}}
14-
providing access to the payload data of the record.</p>
15-
16-
<p>It provides access to a raw content of the record and thus data consumer might need to
17-
decode it.</p>
13+
property of the {{DOMxRef("NDEFRecord")}} interface returns a
14+
{{jsxref("DataView")}} containing the raw bytes of the record's payload.</p>
1815

1916
<h2 id="Syntax">Syntax</h2>
2017

21-
<pre class="brush: js"><em>NDEFRecord</em>.data</pre>
18+
<pre class="brush: js">NDEFRecord.data</pre>
2219

2320
<h3 id="Value">Value</h3>
2421

2522
<p>A {{jsxref("DataView")}} that contains encoded payload data of the record.</p>
2623

24+
<h2 id="Examples">Examples</h2>
25+
26+
<p>The following example loops over the records in an {{domxref("NDEFMessage")}}
27+
object, which is retrieved from {{domxref("NDEFReadingEvent.message")}}. After
28+
selecting a record based on its {{domxref("NDEFRecord.mediaType",
29+
"mediaType")}}, it then decodes what's stored in the <code>data</code> property.</p>
30+
31+
<pre class="brush: js">const ndef = new NDEFReader();
32+
await ndef.scan();
33+
ndef.onreading = (event) => {
34+
const decoder = new TextDecoder();
35+
for (const record of event.message.records) {
36+
if (record.mediaType === "application/json") {
37+
const json = JSON.parse(decoder.decode(record.data));
38+
const article =/^[aeio]/i.test(json.title) ? "an" : "a";
39+
console.log(`${json.name} is ${article} ${json.title}`);
40+
}
41+
}
42+
};</pre>
43+
2744
<h2 id="Specifications">Specifications</h2>
2845

2946
{{Specifications}}

‎files/en-us/web/api/ndefrecord/encoding/index.html

+6-8
Original file line numberDiff line numberDiff line change
@@ -8,21 +8,19 @@
88
- Web NFC
99
browser-compat: api.NDEFRecord.encoding
1010
---
11-
<p>{{Draft}}{{securecontext_header}}{{SeeCompatTable}}{{APIRef()}}</p>
12-
13-
<p class="summary"><span class="seoSummary">The <strong><code>encoding</code></strong>
14-
property ofthe {{DOMxRef("NDEFRecord")}} interface is {{DOMxRef("USVString")}}
15-
containing the name of the encoding used to encode NDEF payload if it contains textual
16-
data.</span></p>
11+
<p>{{securecontext_header}}{{SeeCompatTable}}{{APIRef()}}</p>
12+
<span class="seoSummary">The <strong><code>encoding</code></strong>
13+
property of the {{DOMxRef("NDEFRecord")}} interface returns the encoding of
14+
a textual payload, or <code>null</code> otherwise.
1715

1816
<h2 id="Syntax">Syntax</h2>
1917

20-
<pre class="brush: js"><em>NDEFRecord</em>.encoding</pre>
18+
<pre class="brush: js">NDEFRecord.encoding</pre>
2119

2220
<h3 id="Value">Value</h3>
2321

2422
<p>A {{DOMxRef("USVString")}} which can be one of the following: <code>"utf-8"</code>,
25-
<code>"utf-16"</code>, <code>"utf-16le"</code> or <code>"utf-16be"</code>.</p>
23+
<code>"utf-16"</code>, <code>"utf-16le"</code>, or <code>"utf-16be"</code>.</p>
2624

2725
<h2 id="Specifications">Specifications</h2>
2826

‎files/en-us/web/api/ndefrecord/id/index.html

+5-5
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,11 @@
88
- Web NFC
99
browser-compat: api.NDEFRecord.id
1010
---
11-
<p>{{Draft}}{{securecontext_header}}{{SeeCompatTable}}{{APIRef()}}</p>
11+
<p>{{securecontext_header}}{{SeeCompatTable}}{{APIRef()}}</p>
1212

13-
<p class="summary"><span class="seoSummary">The <strong><code>id</code></strong> property
14-
ofthe {{DOMxRef("NDEFRecord")}} interface is {{DOMxRef("USVString")}} containing the
15-
record identifier.</span></p>
13+
<p class="summary">The <strong><code>id</code></strong> property of the
14+
{{DOMxRef("NDEFRecord")}} interface returns the record identifier, which is an
15+
absolute or relative URL used to identify the record.</p>
1616

1717
<p>This identifier is created by the generator of the record which is solely responsible
1818
for enforcing record identifier uniqueness. Web NFC does not sign the NFC content, thus
@@ -21,7 +21,7 @@
2121

2222
<h2 id="Syntax">Syntax</h2>
2323

24-
<pre class="brush: js"><em>NDEFRecord</em>.id</pre>
24+
<pre class="brush: js">NDEFRecord.id</pre>
2525

2626
<h3 id="Value">Value</h3>
2727

‎files/en-us/web/api/ndefrecord/index.html

+17-12
Original file line numberDiff line numberDiff line change
@@ -7,40 +7,45 @@
77
- Web NFC
88
browser-compat: api.NDEFRecord
99
---
10-
<p>{{Draft}}{{securecontext_header}}{{SeeCompatTable}}{{APIRef()}}</p>
10+
<p>{{securecontext_header}}{{SeeCompatTable}}{{APIRef()}}</p>
1111

12-
<p class="summary"><span class="seoSummary">The <strong><code>NDEFRecord</code></strong> interface of the <a href="/en-US/docs/Web/API/Web_NFC_API">Web NFC API</a> is an abstract interface that represents data that can be read from or written to compatible NFC devices, e.g. NFC tags supporting NDEF.</span></p>
12+
<p class="summary">The <strong><code>NDEFRecord</code></strong> interface of the <a href="/en-US/docs/Web/API/Web_NFC_API">Web NFC API</a> provides data that can be read from, or written to, compatible NFC devices, e.g. NFC tags supporting NDEF.</p>
1313

1414
<h2 id="Constructor">Constructor</h2>
1515

1616
<dl>
1717
<dt>{{DOMxRef("NDEFRecord.NDEFRecord", "NDEFRecord()")}} {{Experimental_Inline}}</dt>
18-
<dd>Returns a new <code>NDEFRecord</code> with configuration specified in the parameters or default ones if no parameters are specified.</dd>
18+
<dd>Returns a new <code>NDEFRecord</code>.</dd>
1919
</dl>
2020

21-
<h2 id="Attributes">Attributes</h2>
21+
<h2 id="Properties">Properties</h2>
2222

2323
<dl>
2424
<dt>{{DOMxRef("NDEFRecord.recordType")}} {{Experimental_Inline}} {{ReadOnlyInline}}</dt>
25-
<dd>Represents the NDEF record type.</dd>
25+
<dd>Returns the record type of the record. Records must have either a standardized well-known type name such as <code>"empty"</code>, <code>"text"</code>, <code>"url"</code>, <code>"smart-poster"</code>, <code>"absolute-url"</code>, <code>"mime"</code>, or <code>"unknown"</code> or else an external type name, which consists of a domain name and custom type name separated by a colon (":").</dd>
26+
2627
<dt>{{DOMxRef("NDEFRecord.mediaType")}} {{Experimental_Inline}} {{ReadOnlyInline}}</dt>
27-
<dd>Represents the {{Glossary("MIME type")}} of the NDEF record payload.</dd>
28+
<dd>Returns the {{Glossary("MIME type")}} of the record. This value will be <code>null</code> if <code>recordType</code> is not equal to <code>"mime"</code>.</dd>
29+
2830
<dt>{{DOMxRef("NDEFRecord.id")}} {{Experimental_Inline}} {{ReadOnlyInline}}</dt>
29-
<dd>Represents the identificator of the record.<br>
30-
<strong>Note:</strong> the uniqueness of the identifier is enforced only by the generator of the record.</dd>
31+
<dd>Returns the record identifier, which is an absolute or relative URL used to identify the record.<br>
32+
<strong>Note:</strong> The uniqueness of the identifier is enforced only by the generator of the record.</dd>
33+
3134
<dt>{{DOMxRef("NDEFRecord.data")}} {{Experimental_Inline}} {{ReadOnlyInline}}</dt>
32-
<dd>Represents the payload of the record.</dd>
35+
<dd>Returns a {{jsxref("DataView")}} containing the raw bytes of the record's payload.</dd>
36+
3337
<dt>{{DOMxRef("NDEFRecord.encoding")}} {{Experimental_Inline}} {{ReadOnlyInline}}</dt>
34-
<dd>Represents the encoding name used for encoding the payload in the case it is textual data.</dd>
38+
<dd>Returns the encoding of a textual payload, or <code>null</code> otherwise.</dd>
39+
3540
<dt>{{DOMxRef("NDEFRecord.lang")}} {{Experimental_Inline}} {{ReadOnlyInline}}</dt>
36-
<dd>Represents a language tag of the content, if it was encoded.</dd>
41+
<dd>Returns the language of a textual payload, or <code>null</code> if one was not supplied.</dd>
3742
</dl>
3843

3944
<h2 id="Methods">Methods</h2>
4045

4146
<dl>
4247
<dt>{{DOMxRef("NDEFRecord.toRecords", "NDEFRecord.toRecords()")}} {{Experimental_Inline}}</dt>
43-
<dd>Coverts {{DOMxRef("NDEFRecord.data")}} to sequence of records.</dd>
48+
<dd>Converts {{DOMxRef("NDEFRecord.data")}} to a sequence of records. This allows parsing the payloads of record types which may contain nested records, such as smart poster and external type records.</dd>
4449
</dl>
4550

4651
<h2 id="Specifications">Specifications</h2>

‎files/en-us/web/api/ndefrecord/lang/index.html

+5-6
Original file line numberDiff line numberDiff line change
@@ -7,19 +7,18 @@
77
- Web NFC
88
browser-compat: api.NDEFRecord.lang
99
---
10-
<p>{{Draft}}{{securecontext_header}}{{SeeCompatTable}}{{APIRef()}}</p>
10+
<p>{{securecontext_header}}{{SeeCompatTable}}{{APIRef()}}</p>
1111

12-
<p class="summary"><span class="seoSummary">The <strong><code>lang</code></strong>
13-
property ofthe {{DOMxRef("NDEFRecord")}} interface is {{DOMxRef("USVString")}}
14-
containing the {{Glossary("language tag")}} of the record contents, if it is a
15-
vailable.</span></p>
12+
<p class="summary">The <strong><code>lang</code></strong>
13+
property of the {{DOMxRef("NDEFRecord")}} interface returns the language of
14+
a textual payload, or <code>null</code> if one was not supplied.</p>
1615

1716
<p>The record might be missing a language tag, for example, if the recorded information is
1817
not locale-specific.</p>
1918

2019
<h2 id="Syntax">Syntax</h2>
2120

22-
<pre class="brush: js"><em>NDEFRecord</em>.lang</pre>
21+
<pre class="brush: js">NDEFRecord.lang</pre>
2322

2423
<h3 id="Value">Value</h3>
2524

‎files/en-us/web/api/ndefrecord/mediatype/index.html

+22-6
Original file line numberDiff line numberDiff line change
@@ -7,21 +7,37 @@
77
- Web NFC
88
browser-compat: api.NDEFRecord.mediaType
99
---
10-
<p>{{Draft}}{{securecontext_header}}{{SeeCompatTable}}{{APIRef()}}</p>
10+
<p>{{securecontext_header}}{{SeeCompatTable}}{{APIRef()}}</p>
1111

12-
<p class="summary"><span class="seoSummary">The <strong><code>mediaType</code></strong>
13-
property ofthe {{DOMxRef("NDEFRecord")}} interface is {{DOMxRef("USVString")}}
14-
containing the {{Glossary("MIME type")}} of the record payload.</span></p>
12+
<p class="summary">The <strong><code>mediaType</code></strong>
13+
property of the {{DOMxRef("NDEFRecord")}} interface returns the {{Glossary("MIME type")}} of the record. This value will be <code>null</code> if <code>recordType</code> is not equal to <code>"mime"</code>.</p>
1514

1615
<h2 id="Syntax">Syntax</h2>
1716

18-
<pre class="brush: js"><em>NDEFRecord</em>.mediaType</pre>
17+
<pre class="brush: js">NDEFRecord.mediaType</pre>
1918

2019
<h3 id="Value">Value</h3>
2120

22-
<p>A {{DOMxRef("USVString")}}, corresponding to a {{Glossary("MIME type")}} of the record
21+
<p>A {{DOMxRef("USVString")}}, containing the {{Glossary("MIME type")}} of the record
2322
payload.</p>
2423

24+
<h2 id="Examples">Examples</h2>
25+
26+
<p>The following example loops over the records in an {{domxref("NDEFMessage")}} object, which is retrieved from {{domxref("NDEFReadingEvent.message")}}. It then uses the <code>mediaType</code> property to determine which of the records to parse.</p>
27+
28+
<pre class="brush: js">const ndef = new NDEFReader();
29+
await ndef.scan();
30+
ndef.onreading = (event) => {
31+
const decoder = new TextDecoder();
32+
for (const record of event.message.records) {
33+
if (record.mediaType === "application/json") {
34+
const json = JSON.parse(decoder.decode(record.data));
35+
const article =/^[aeio]/i.test(json.title) ? "an" : "a";
36+
console.log(`${json.name} is ${article} ${json.title}`);
37+
}
38+
}
39+
};</pre>
40+
2541
<h2 id="Specifications">Specifications</h2>
2642

2743
{{Specifications}}

‎files/en-us/web/api/ndefrecord/ndefrecord/index.html

+39-6
Original file line numberDiff line numberDiff line change
@@ -7,24 +7,57 @@
77
- Web NFC
88
browser-compat: api.NDEFRecord.NDEFRecord
99
---
10-
<p>{{Draft}}{{securecontext_header}}{{SeeCompatTable}}{{APIRef()}}</p>
10+
<p>{{securecontext_header}}{{SeeCompatTable}}{{APIRef()}}</p>
1111

12-
<p class="summary"><span class="seoSummary">The <strong><code>NDEFRecord()</code></strong>
12+
<p class="summary">The <strong><code>NDEFRecord()</code></strong>
1313
constructor of the <a href="/en-US/docs/Web/API/WebNFC_API">Web NFC API</a> returns a
1414
newly constructed {{DOMxRef("NDEFRecord")}} object that represents data that can be
15-
read from or written to compatible NFC devices, e.g. NFC tags supporting NDEF.</span>
15+
read from, or written to, compatible NFC devices; e.g. NFC tags supporting NDEF.
1616
</p>
1717

1818
<h2 id="Syntax">Syntax</h2>
1919

20-
<pre class="brush: js"><em>writer</em> = new NDEFRecord(<em>NDEFRecordInit</em>);
20+
<pre class="brush: js">writer = new NDEFRecord(options);
2121
</pre>
2222

2323
<h3 id="Parameters">Parameters</h3>
2424

2525
<dl>
26-
<dt><code>NDEFRecordInit</code> {{Experimental_Inline}} {{ReadOnlyInline}}</dt>
27-
<dd>{{DOMxRef("NDEFRecordInit")}} with initialization data.</dd>
26+
<dt><code>options</code></dt>
27+
<dd>An object with the following properties:
28+
<dl>
29+
<dt><code>data</code> {{optional_inline}}</dt>
30+
<dd>Contains the data to be transmitted; one of a string, a {{domxref("BufferSource")}}, or an array of nested records.</dd>
31+
<dt><code>encoding</code> {{optional_inline}}</dt>
32+
<dd>A string specifying the record's encoding.</dd>
33+
<dt><code>id</code> {{optional_inline}}</dt>
34+
<dd>A developer-defined identifier for the record.</dd>
35+
<dt><code>lang</code> {{optional_inline}}</dt>
36+
<dd>A valid <a href="https://www.rfc-editor.org/info/bcp47">BCP47</a> language tag.</dd>
37+
<dt><code>mediaType</code> {{optional_inline}}</dt>
38+
<dd>A valid <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types">MIME type</a>.</dd>
39+
<dt><code>recordType</code></dt>
40+
<dd>A string indicating the type of data stored in <code>data</code>. It must be one of the following values:
41+
<dl>
42+
<dt><code>"absolute-url"</code></dt>
43+
<dt>An absolute URL to the data.</dt>
44+
<dt><code>"empty"</code></dt>
45+
<dd>An empty {{domxref("NDEFRecord")}}.</dd>
46+
<dt><code>"mime"</code></dt>
47+
<dd>A valid <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types">MIME type</a>.</dd>
48+
<dt><code>"smart-poster"</code></dt>
49+
<dd>A smart poster as defined by the <a href="https://w3c.github.io/web-nfc/#bib-ndef-smartposter">NDEF-SMARTPOSTER</a> specification.</dd>
50+
<dt><code>"text"</code></dt>
51+
<dd>Text as defined by the <a href="https://w3c.github.io/web-nfc/#bib-ndef-text">NDEF-TEXT</a> specification.</dd>
52+
<dt><code>"unknown"</code></dt>
53+
<dd>The record type is not known.</dd>
54+
<dt><code>"URL"</code></dt>
55+
<dd>A URL as defined by the <a href="https://w3c.github.io/web-nfc/#bib-ndef-uri">NDEF-URI</a> specification.</dd>
56+
</dl>
57+
</dd>
58+
</dl>
59+
60+
</dd>
2861
</dl>
2962

3063
<h3 id="Return_value">Return value</h3>

‎files/en-us/web/api/ndefrecord/recordtype/index.html

+13-15
Original file line numberDiff line numberDiff line change
@@ -7,41 +7,39 @@
77
- Web NFC
88
browser-compat: api.NDEFRecord.recordType
99
---
10-
<p>{{Draft}}{{securecontext_header}}{{SeeCompatTable}}{{APIRef()}}</p>
10+
<p>{{securecontext_header}}{{SeeCompatTable}}{{APIRef()}}</p>
1111

12-
<p class="summary"><span class="seoSummary">The <strong><code>recordType</code></strong>
13-
property ofthe {{DOMxRef("NDEFRecord")}} interface is {{DOMxRef("USVString")}}
14-
containing the NDEF record type.</span></p>
12+
<p class="summary">The <strong><code>recordType</code></strong>
13+
property of the {{DOMxRef("NDEFRecord")}} interface returns the record type of the record.</p>
1514

1615
<h2 id="Syntax">Syntax</h2>
1716

18-
<pre class="brush: js"><em>NDEFRecord</em>.recordType</pre>
17+
<pre class="brush: js">NDEFRecord.recordType</pre>
1918

2019
<h3 id="Value">Value</h3>
2120

2221
<p>A {{DOMxRef("USVString")}} which can be one of the following:</p>
2322

2423
<dl>
2524
<dt><code>"empty"</code></dt>
26-
<dd>Represents a empty NDEF record.</dd>
25+
<dd>An empty NDEF record.</dd>
2726
<dt><code>"text"</code></dt>
28-
<dd>Represents a text NDEF record.</dd>
27+
<dd>A text NDEF record.</dd>
2928
<dt><code>"url"</code></dt>
30-
<dd>Represents an URI NDEF record.</dd>
31-
<dt><code>"<dfn>smart-poster</dfn>"</code></dt>
32-
<dd>Represents a "smart poster" NDEF record.</dd>
29+
<dd>A URI NDEF record.</dd>
30+
<dt><code>"smart-poster"</code></dt>
31+
<dd>A "smart poster" NDEF record.</dd>
3332
<dt><code>"absolute-url"</code></dt>
34-
<dd>Represents an absolute URL NDEF record.</dd>
33+
<dd>An absolute URL NDEF record.</dd>
3534
<dt><code>"mime"</code></dt>
36-
<dd>Represents a {{Glossary("MIME type")}} NDEF record.</dd>
35+
<dd>A {{Glossary("MIME type")}} NDEF record.</dd>
3736
<dt><code>"unknown"</code></dt>
38-
<dd>Represents an unknown NDEF record.</dd>
37+
<dd>The NDEF record type is not known.</dd>
3938
<dt>local type name</dt>
4039
<dd>Represents a local type name, frequently used to specify NDEF record embedded within
4140
another record.</dd>
4241
<dt>external type name</dt>
43-
<dd>Represents a custom record type name that can be creted by organizations themselves
44-
for custom needs.</dd>
42+
<dd>A custom string consisting of a domain name and custom type name separated by a colon (":").</dd>
4543
</dl>
4644

4745
<h2 id="Specifications">Specifications</h2>

0 commit comments

Comments
 (0)