Skip to content

Commit fce59e0

Browse files
chrisdavidmillshamishwillee
chrisdavidmills
and
hamishwillee
authored
Technical review: Add documentation for the geolocation element (#42772)
* Add documentation for the geolocation element * Create HTMLGeolocationElement page and make some fixes * Add HTMLGeolocationElement properties * Add links to demos, and tweak code examples * Add event pages and make a few more tweaks * Add documentation for the geolocation element * Create HTMLGeolocationElement page and make some fixes * Add HTMLGeolocationElement properties * Add links to demos, and tweak code examples * Add event pages and make a few more tweaks * Update files/en-us/web/html/reference/elements/geolocation/index.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Update files/en-us/web/html/reference/elements/geolocation/index.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Update files/en-us/web/html/reference/elements/geolocation/index.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Update files/en-us/web/html/reference/elements/geolocation/index.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Update files/en-us/web/html/reference/elements/geolocation/index.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Update files/en-us/web/html/reference/elements/geolocation/index.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Update files/en-us/web/html/reference/elements/geolocation/index.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Update files/en-us/web/html/reference/elements/geolocation/index.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Update files/en-us/web/api/htmlgeolocationelement/index.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Update files/en-us/web/api/htmlgeolocationelement/index.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Update files/en-us/web/api/htmlgeolocationelement/index.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Update files/en-us/web/api/htmlgeolocationelement/autolocate/index.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Update files/en-us/web/api/htmlgeolocationelement/autolocate/index.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Update files/en-us/web/api/htmlgeolocationelement/initialpermissionstatus/index.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Update files/en-us/web/api/htmlgeolocationelement/permissionstatus/index.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Update files/en-us/web/api/htmlgeolocationelement/location_event/index.md Co-authored-by: Hamish Willee <hamishwillee@gmail.com> * Fixes for hamish review comments * Final few changes * Apply suggestions from code review --------- Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
1 parent d63fef1 commit fce59e0

File tree

20 files changed

+1596
-5
lines changed

20 files changed

+1596
-5
lines changed

‎files/en-us/web/api/geolocation_api/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,9 @@ The **Geolocation API** allows the user to provide their location to web applica
1111

1212
WebExtensions that wish to use the `Geolocation` object must add the `"geolocation"` permission to their manifest. The user's operating system will prompt the user to allow location access the first time it is requested.
1313

14+
> [!NOTE]
15+
> The {{htmlelement("geolocation")}} element provides an alternative mechanism for accessing and handling geolocation data that solves some of the shortcomings of the Geolocation API: It provides a consistent UI, and a more intuitive permission management process.
16+
1417
## Concepts and usage
1518

1619
You will often want to retrieve a user's location information in your web app, for example to plot their location on a map, or display personalized information relevant to their location.
@@ -87,5 +90,6 @@ As Wi-Fi-based locating is often provided by Google, the vanilla Geolocation API
8790

8891
## See also
8992

93+
- {{htmlelement("geolocation")}} element
9094
- [Using the Geolocation API](/en-US/docs/Web/API/Geolocation_API/Using_the_Geolocation_API)
9195
- [Who moved my geolocation?](https://hacks.mozilla.org/2013/10/who-moved-my-geolocation/) (Hacks blog)

‎files/en-us/web/api/geolocation_api/using_the_geolocation_api/index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -173,3 +173,7 @@ document.querySelector("#find-me").addEventListener("click", geoFindMe);
173173
### Result
174174

175175
{{EmbedLiveSample('Examples', 350, 150, "", "", "", "geolocation")}}
176+
177+
## See also
178+
179+
- {{htmlelement("geolocation")}} element

‎files/en-us/web/api/htmlgeolocationelement/autolocate/index.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: "HTMLGeolocationElement: autolocate property"
3+
short-title: autolocate
4+
slug: Web/API/HTMLGeolocationElement/autolocate
5+
page-type: web-api-instance-property
6+
browser-compat: api.HTMLGeolocationElement.autolocate
7+
---
8+
9+
{{APIRef("Navigation API")}}
10+
11+
The **`autolocate`** property of the {{domxref("HTMLGeolocationElement")}} interface gets and sets a boolean value indicating whether the browser should immediately request location data when the {{htmlelement("geolocation")}} element is rendered, provided permission to use the `geolocation` feature is already granted.
12+
13+
It reflects the value of the `<geolocation>` [`autolocate`](/en-US/docs/Web/HTML/Reference/Elements/geolocation#autolocate) attribute.
14+
15+
## Value
16+
17+
A boolean value:
18+
19+
- If `true`, location data is requested as soon as the `<geolocation>` element is rendered, provided permission to use the `geolocation` feature was previously granted.
20+
- If `false`, location data is only requested when the user presses the `<geolocation>` button.
21+
22+
Defaults to `false`.
23+
24+
If permission to use the `geolocation` feature was not previously granted, the `autolocate` property is ignored.
25+
26+
## Examples
27+
28+
### Basic usage
29+
30+
```html
31+
<geolocation autolocate></geolocation>
32+
```
33+
34+
```js
35+
const geo = document.querySelector("geolocation");
36+
console.log(geo.autolocate); // true
37+
```
38+
39+
See our [Embedded map example walkthrough](/en-US/docs/Web/API/HTMLGeolocationElement#embedded_map_example) for a real-world example that includes `autolocate`.
40+
41+
## Specifications
42+
43+
{{Specifications}}
44+
45+
## Browser compatibility
46+
47+
{{Compat}}
48+
49+
## See also
50+
51+
- {{htmlelement("geolocation")}} element

‎files/en-us/web/api/htmlgeolocationelement/error/index.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
title: "HTMLGeolocationElement: error property"
3+
short-title: error
4+
slug: Web/API/HTMLGeolocationElement/error
5+
page-type: web-api-instance-property
6+
browser-compat: api.HTMLGeolocationElement.error
7+
---
8+
9+
{{APIRef("Navigation API")}}
10+
11+
The **`error`** read-only property of the {{domxref("HTMLGeolocationElement")}} interface returns a {{domxref("GeolocationPositionError")}} object representing error information, in the event of a failure to retrieve location data.
12+
13+
If location data retrieval is successful, the data is available in the {{domxref("HTMLGeolocationElement.position")}} property.
14+
15+
## Value
16+
17+
A {{domxref("GeolocationPositionError")}} object, or `null` if location data was successfully retrieved.
18+
19+
## Examples
20+
21+
### Basic usage
22+
23+
```html
24+
<geolocation autolocate></geolocation>
25+
```
26+
27+
```js
28+
const geo = document.querySelector("geolocation");
29+
geo.addEventListener("location", () => {
30+
if (geo.position) {
31+
console.log(
32+
`(${geo.position.coords.latitude},${geo.position.coords.longitude})`,
33+
);
34+
} else if (geo.error) {
35+
console.log(geo.error.message);
36+
}
37+
});
38+
```
39+
40+
See our [Embedded map example walkthrough](/en-US/docs/Web/API/HTMLGeolocationElement#embedded_map_example) for a real-world example that includes `error`.
41+
42+
## Specifications
43+
44+
{{Specifications}}
45+
46+
## Browser compatibility
47+
48+
{{Compat}}
49+
50+
## See also
51+
52+
- {{htmlelement("geolocation")}} element

‎files/en-us/web/api/htmlgeolocationelement/htmlgeolocationelement/index.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
title: "HTMLGeolocationElement: HTMLGeolocationElement() constructor"
3+
short-title: HTMLGeolocationElement()
4+
slug: Web/API/HTMLGeolocationElement/HTMLGeolocationElement
5+
page-type: web-api-constructor
6+
browser-compat: api.HTMLGeolocationElement.HTMLGeolocationElement
7+
---
8+
9+
{{APIRef("HTML DOM")}}
10+
11+
The **`HTMLGeolocationElement()`** constructor creates a new {{domxref("HTMLGeolocationElement")}} object instance.
12+
13+
## Syntax
14+
15+
```js-nolint
16+
new HTMLGeolocationElement()
17+
```
18+
19+
### Parameters
20+
21+
None.
22+
23+
### Return value
24+
25+
A new {{domxref("HTMLGeolocationElement")}} object instance, if used internally by the browser.
26+
27+
Developers cannot use the `HTMLGeolocationElement()` constructor directly to create a new `HTMLGeolocationElement` instance: attempting to do so results in an "illegal constructor" error.
28+
29+
### Examples
30+
31+
#### Creating a new `HTMLGeolocationElement` instance programmatically
32+
33+
To programmatically create a new `HTMLGeolocationElement` instance, instead of trying to use the contructor directly, you would create a new {{htmlelement("geolocation")}} element instance using {{domxref("Document.createElement()")}}:
34+
35+
```js
36+
const geo = document.createElement("geolocation");
37+
```
38+
39+
You can then use it by appending it to the DOM:
40+
41+
```js
42+
document.body.append(geo);
43+
```
44+
45+
## Specifications
46+
47+
{{Specifications}}
48+
49+
## Browser compatibility
50+
51+
{{Compat}}
52+
53+
## See also
54+
55+
- {{htmlelement("geolocation")}} element

0 commit comments

Comments
 (0)