Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add React setup instructions to documentation #346

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add React setup instructions to documentation #346

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9945574
Add React setup instructions to documentation
AdarshSahani003 Nov 4, 2024
269027a
Addressed review comments and made requested changes
AdarshSahani003 Nov 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 36 additions & 14 deletions guide/src/web-getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
This section of the guide covers how to integrate Ferrostar into a web app.
While there are limitations to the web [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API)
(notably no background updates),
PWAs and other mobile-optimized sites
**Progressive Web Apps (PWAs)** and other mobile-optimized sites
can be a great solution when a native iOS/Android app is impractical or prohibitively expensive.

We'll cover the "batteries included" approach, but flag areas for customization and overrides along the way.
Expand Down Expand Up @@ -33,7 +33,7 @@ Then add `wasm()` and `topLevelAwait()` to the `plugins` section of your Vite co

TODO

## Add Ferrostar web components to your web app
## Add Ferrostar web components to your Web App

The Ferrostar web SDK uses the [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)
to ensure maximum compatibility across frontend frameworks.
Expand All @@ -43,35 +43,57 @@ You can import the components just like other things you’re used to in JavaScr
import { FerrostarMap, BrowserLocationProvider } from "@stadiamaps/ferrostar-components";
```

## Configure the `<ferrostar-map>` component
## Configure the <ferrostar-map> Component

Now you can use Ferrostar in your HTML like this:
Now you can use Ferrostar in your web component like this:

```html
## HTML

```
<ferrostar-map
id="ferrostar"
id="ferrostar"
valhallaEndpointUrl="https://api.stadiamaps.com/route/v1"
styleUrl="https://tiles.stadiamaps.com/styles/outdoors.json"
profile="bicycle"
></ferrostar-map>
```

Here we have used Stadia Maps URLs, which should work without authentication for local development.
(Refer to the [authentication docs](https://docs.stadiamaps.com/authentication/)
for network deployment details; you can start with a free account.)
AdarshSahani003 marked this conversation as resolved.
Show resolved Hide resolved
## React
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe that the first example should remain generic, and we should have separate sections for framework-specific (React, Vue, etc.) code. This appears to replace the generic code, which is applicable to a large number of users, with a React-specific example.


```javascript
import React from 'react';
import { FerrostarMap } from "@stadiamaps/ferrostar-webcomponents";

const MyMapComponent = () => {
return (
<ferrostar-map
id="ferrostar"
valhallaEndpointUrl="https://api.stadiamaps.com/route/v1"
styleUrl="https://tiles.stadiamaps.com/styles/outdoors.json"
profile="bicycle"
style={{ display: 'block', width: '100%', height: '100%' }} ></ferrostar-map>
);
};

export default MyMapComponent;
```

---

See the [vendors appendix](./vendors.md) for a list of other compatible vendors.
## CSS Requirements

`<ferrostar-map>` additionally requires setting some CSS manually, or it will be invisible!
The `<ferrostar-map>` component requires setting some CSS manually; otherwise, it will be invisible!

```css
ferrostar-map {
display: block;
width: 100%;
height: 100%;
display: block;
width: 100%;
height: 100%;
}
```

---

That’s all you need to get started!

### Configuration explained
Expand Down