diff --git a/README.md b/README.md index be62bb92..c30f6061 100644 --- a/README.md +++ b/README.md @@ -20,8 +20,13 @@ yarn run config # add the mandato yarn run dev # start the dev server, this will open a browser in localhost:3000 ``` -See the [Environment configuration variables](docs/env.md) documentation for more information of the -required configuration variables. +You can also follow along the +[Getting started with FTW](https://www.sharetribe.com/docs/tutorials/getting-started-with-ftw/) +tutorial in the [Flex Docs website](https://www.sharetribe.com/docs/). + +For more information of the configuration, see the +[FTW Environment configuration variables](https://www.sharetribe.com/docs/references/ftw-env/) +reference in Flex Docs. **Note:** If you want to build your own Flex marketplace on top of the template, you should fork the repository instead of cloning it. See the [Customization guide](./docs/customization-guide.md). diff --git a/docs/README.md b/docs/README.md index 93e47121..29e1e6d3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -13,15 +13,33 @@ used in a browser environment using the JavaScript SDK. Marketplace features included in Saunatime: -- **Location search** shows the user if there are saunas available in a given location. -- **The listing page** gives a detailed view about what a particular sauna offers. -- **Transaction process**: Saunatime uses nightly booking. -- **Notifications**: Emails are sent during the booking process to alert customers and providers +* **Location search** shows the user if there are saunas available in a given location. +* **The listing page** gives a detailed view about what a particular sauna offers. +* **Transaction process**: Saunatime uses nightly booking. +* **Notifications**: Emails are sent during the booking process to alert customers and providers about changes in the booking state. -- **Inbox** lists **orders** and **sales**. -- **Reviews** can be given after a completed transaction. -- **User profiles** provide detailed information about a given user. -- **Extended data:** The listing and user data models are modified using extended data. +* **Inbox** lists **orders** and **sales**. +* **Reviews** can be given after a completed transaction. +* **User profiles** provide detailed information about a given user. +* **Extended data:** The listing and user data models are modified using extended data. + +## Flex Docs website + +We are currently moving documentation to the Flex Docs site, so at the moment part of the +documentation is in this repository and part is in the Flex Docs site. + +See the Flex Docs site: https://www.sharetribe.com/docs/ + +## Getting started + +We recommend going through the +[Getting started articles](https://www.sharetribe.com/docs/background/getting-started/) in the Flex +Docs: + +* [Introducing Flex](https://www.sharetribe.com/docs/background/introducing-flex/) +* [What development skills are needed?](https://www.sharetribe.com/docs/background/development-skills/) +* [Getting started with FTW](https://www.sharetribe.com/docs/tutorials/getting-started-with-ftw/) + tutorial. ## How to customize this template @@ -33,28 +51,34 @@ The easiest way to start a customization project is to read through the Documentation for specific topics can be found in the following files: -- [Customization guide](customization-guide.md) -- [Folder structure](folder-structure.md) -- [Integration to map providers](map-providers.md) -- [Translations](translations.md) -- [Styling a marketplace](styling.md) -- [Static pages](static-pages.md) -- [Terms of Service and Privacy Policy](terms-of-service-and-privacy-policy.md) -- [Routing](routing.md) -- [Redux and duck files](redux.md) -- [Extended data](extended-data.md) -- [Extend the listing data model](extend-listing.md) -- [Search filters](search-filters.md) -- [Testing](testing.md) -- [Error logging with Sentry](sentry.md) -- [Analytics](analytics.md) -- [Continuous Integration (CI)](ci.md) -- [Content Security Policy (CSP)](content-security-policy.md) -- [Original create-react-app documentation](https://github.com/sharetribe/create-react-app/blob/master/packages/react-scripts/template/README.md) -- [Customization checklist](customization-checklist.md) -- [Icons](icons.md) -- [Improving performance](improving-performance.md) -- [Deploying to production](deploying-to-production.md) +* [Customization guide](customization-guide.md) +* [Folder structure](folder-structure.md) +* [Translations](translations.md) +* [Styling a marketplace](styling.md) +* [Static pages](static-pages.md) +* [Terms of Service and Privacy Policy](terms-of-service-and-privacy-policy.md) +* [Routing](routing.md) +* [Redux and duck files](redux.md) +* [Extended data](extended-data.md) + * See also the + [Extended data reference](https://www.sharetribe.com/docs/references/extended-data/) in Flex + Docs +* [Extend the listing data model](extend-listing.md) +* [Search filters](search-filters.md) +* [Testing](testing.md) +* [Continuous Integration (CI)](ci.md) +* [Original create-react-app documentation](https://github.com/sharetribe/create-react-app/blob/master/packages/react-scripts/template/README.md) +* [Customization checklist](customization-checklist.md) +* [Icons](icons.md) +* [Improving performance](improving-performance.md) +* [Deploying to production](deploying-to-production.md) + +See also the following articles in the [Flex Docs](https://www.sharetribe.com/docs/) website: + +* [How to set up Mapbox for FTW](https://www.sharetribe.com/docs/guides/how-to-set-up-mapbox-for-ftw/) +* [How to set up Sentry to log errors in FTW](https://www.sharetribe.com/docs/guides/how-to-set-up-sentry-to-log-errors-in-ftw/) +* [How to set up Analytics for FTW](https://www.sharetribe.com/docs/guides/how-to-set-up-analytics-for-ftw/) +* [How to set up Content Security Policy (CSP) for FTW](https://www.sharetribe.com/docs/guides/how-to-set-up-csp-for-ftw/) The application was bootstrapped with a forked version of [create-react-app](https://github.com/facebookincubator/create-react-app). While most of the diff --git a/docs/analytics.md b/docs/analytics.md index 9c855d63..b65bdc6f 100644 --- a/docs/analytics.md +++ b/docs/analytics.md @@ -1,37 +1,5 @@ # Analytics -The application supports tracking page views with pluggable analytics handlers. +Documentation moved to the Flex Docs site: -## Google Analytics - -Google Analytics (GA) is supported by default. The enable GA, set the GA tracker ID to the -environment variable `REACT_APP_GOOGLE_ANALYTICS_ID`; - -## Custom analytics handler - -If you want to add a new analytics library, you can do as follows: - -1. Add the analytics library script - - If the analytics library has an external script, add the library script tag to the - [src/public/index.html](../public/index.html) file. If you need more control, see how the GA - script is added in [server/renderer.js](../server/renderer.js). - -1. Create a handler - - To track page views, create a custom handler e.g. in - [src/analytics/handlers.js](../src/analytics/handlers.js). The handler should be a class that - implements a `trackPageView(url)` method. - - Note that the `url` parameter might not be the same as in the URL bar of the browser. It is the - canonical form of the URL. For example, in the listing page it doesn't have the dynamic title - slug in the middle. This allows unified analytics and correct tracking of pages that can be - accessed from multiple different URLs. - - If you analytics library takes the page URL from the browser, you might need to override that - behavior to use the canonical URL that is given to the method. - -1. Initialise the handler - - Initialise the handler in the `setupAnalyticsHandlers()` function in - [src/index.js](../src/index.js). +https://www.sharetribe.com/docs/guides/how-to-set-up-analytics-for-ftw/ diff --git a/docs/content-security-policy.md b/docs/content-security-policy.md index ccf0ec0e..5674053d 100644 --- a/docs/content-security-policy.md +++ b/docs/content-security-policy.md @@ -1,43 +1,5 @@ # Content Security Policy (CSP) -According to [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP): +Documentation moved to the Flex Docs site: -> Content Security Policy (CSP) is an added layer of security that helps to detect and mitigate -> certain types of attacks, including Cross Site Scripting (XSS) and data injection attacks. These -> attacks are used for everything from data theft to site defacement or distribution of malware. - -This document describes how to use a CSP with the Flex template app. By default the CSP is disabled. -By turning it on, the default whitelist in [server/csp.js](../server/csp.js) works with the all the -URLs and tools that come with the application. - -## Setup - -The CSP is configured using the `REACT_APP_CSP` environment variable. - -Possible values: - -- not set: disabled -- `REACT_APP_CSP=report`: Enabled, but policy violations are only reported -- `REACT_APP_CSP=block`: Enabled. Policy violations are reported and requests that violate the - policy are blocked - -If error logging with Sentry is enabled (See [Error logging with Sentry](sentry.md)), the reports -are sent to Sentry. Otherwise the reports are just logged in the backend. - -## Extending the policy - -If you want to whitelist new sources (for example adding a new external analytics service) and keep -the CSP enabled, you should add the domains to the white list in [server/csp.js](../server/csp.js). - -The easiest way to do this is to first turn on the policy in report mode and then see what policy -violations are logged to the browser developer console or to the backend policy violation report -URL. - -## Resources - -To understand what CSP is and how browsers work, here are some resources: - -- https://content-security-policy.com/ -- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -- https://ponyfoo.com/articles/content-security-policy-in-express-apps -- https://helmetjs.github.io/docs/csp/ +https://www.sharetribe.com/docs/guides/how-to-set-up-csp-for-ftw/ diff --git a/docs/customization-checklist.md b/docs/customization-checklist.md index 71c82556..286b0c2c 100644 --- a/docs/customization-checklist.md +++ b/docs/customization-checklist.md @@ -2,40 +2,42 @@ Some generic things to update and check when starting to customize the template. -- [Marketplace colors](styling.md) -- [Generate app icons](icons.md) -- [Update translations](../src/translations/en.json) or [change the language](translations.md) -- [LandingPage](../src/containers/LandingPage/LandingPage.js): update and create branded sections -- [Footer](../src/components/Footer/Footer.js) -- [AboutPage](../src/containers/AboutPage/AboutPage.js) -- [Terms of Service](terms-of-service-and-privacy-policy.md#terms-of-service) -- [Privacy Policy](terms-of-service-and-privacy-policy.md#privacy-policy) -- [Social media sharing graphics](../src/components/Page/Page.js); -- [Logo](../src/components/Logo/Logo.js) Change and check that it works on Topbar, Footer, and +* [Marketplace colors](styling.md) +* [Generate app icons](icons.md) +* [Update translations](../src/translations/en.json) or [change the language](translations.md) +* [LandingPage](../src/containers/LandingPage/LandingPage.js): update and create branded sections +* [Footer](../src/components/Footer/Footer.js) +* [AboutPage](../src/containers/AboutPage/AboutPage.js) +* [Terms of Service](terms-of-service-and-privacy-policy.md#terms-of-service) +* [Privacy Policy](terms-of-service-and-privacy-policy.md#privacy-policy) +* [Social media sharing graphics](../src/components/Page/Page.js); +* [Logo](../src/components/Logo/Logo.js) Change and check that it works on Topbar, Footer, and CheckoutPage -- [Default background image](../src/assets/background-1440.jpg) -- [Maps Marker icon](../src/components/Map/images/marker-32x32.png) -- [Config: update environment variables](../src/config.js) -- [Config: siteTitle](../src/config.js) for page schema (SEO) -- [Config: marketplace address](../src/config.js): contact details also improve SEO -- [Config: social media pages](../src/config.js) -- [Marketplace custom config](../src/marketplace-custom-config.js) -- Update [ListingPage](../src/containers/ListingPage/ListingPage.js) to show extended data (aka +* [Default background image](../src/assets/background-1440.jpg) +* [Maps Marker icon](../src/components/Map/images/marker-32x32.png) +* [Config: update environment variables](../src/config.js) +* [Config: siteTitle](../src/config.js) for page schema (SEO) +* [Config: marketplace address](../src/config.js): contact details also improve SEO +* [Config: social media pages](../src/config.js) +* [Marketplace custom config](../src/marketplace-custom-config.js) +* Update [ListingPage](../src/containers/ListingPage/ListingPage.js) to show extended data (aka publicData attribute) -- Update [EditListingWizard](../src/components/EditListingWizard/EditListingWizard.js) and panels to +* Update [EditListingWizard](../src/components/EditListingWizard/EditListingWizard.js) and panels to add extended data -- Update [SearchPage](../src/containers/SearchPage/SearchPage.js) to filter with extended data -- Update [routeConfiguration](../src/routeConfiguration.js) if needed -- Update [Email templates](../ext/default-mail-templates), all of them: .html, subject.txt, and +* Update [SearchPage](../src/containers/SearchPage/SearchPage.js) to filter with extended data +* Update [routeConfiguration](../src/routeConfiguration.js) if needed +* Update [Email templates](../ext/default-mail-templates), all of them: .html, subject.txt, and text.txt -- Update [config: bookingUnitType](../src/config.js) if needed -- If `line-item/units` is used, add quantity handling to + * See the [Email template reference](https://www.sharetribe.com/docs/references/email-templates/) + in Flex Docs for more information. +* Update [config: bookingUnitType](../src/config.js) if needed +* If `line-item/units` is used, add quantity handling to [BookingDatesForm](../src/forms/BookingDatesForm/BookingDatesForm.js), [ListingPage](../src/containers/ListingPage/ListingPage.js), [CheckoutPage](../src/containers/CheckoutPage/CheckoutPage.js) ## What else -- Do you need more [static pages](static-pages.md)? -- Changes to existing pages -- Changes to transaction process (API + Web app) +* Do you need more [static pages](static-pages.md)? +* Changes to existing pages +* Changes to transaction process (API + Web app) diff --git a/docs/customization-guide.md b/docs/customization-guide.md index 81eaa4d9..ed83448b 100644 --- a/docs/customization-guide.md +++ b/docs/customization-guide.md @@ -7,12 +7,23 @@ will help you in setting up your fork and describes the general workflow. README file, you probably don't want to make the customizations in that project. Forking the repository is the recommended way to proceed. Follow this guide for instructions. +## Getting started + +We recommend going through the +[Getting started articles](https://www.sharetribe.com/docs/background/getting-started/) in the Flex +Docs: + +* [Introducing Flex](https://www.sharetribe.com/docs/background/introducing-flex/) +* [What development skills are needed?](https://www.sharetribe.com/docs/background/development-skills/) +* [Getting started with FTW](https://www.sharetribe.com/docs/tutorials/getting-started-with-ftw/) + tutorial. + ## Requirements Install required tools: -- [Node.js](https://nodejs.org/) -- [Yarn](https://yarnpkg.com/) +* [Node.js](https://nodejs.org/) +* [Yarn](https://yarnpkg.com/) ## Technologies @@ -24,13 +35,13 @@ get-go. Here are some main technologies that the template uses: -- JavaScript: programming language for the whole application -- CSS: styling the user interface using [CSS Modules](https://github.com/css-modules/css-modules) -- [React](https://reactjs.org/): library for creating user interfaces with components -- [Redux](https://redux.js.org/): state and data flow handling -- [Final Form](https://github.com/final-form/final-form): forms -- [React Router](https://reacttraining.com/react-router/): routing -- [Express](https://expressjs.com/): server +* JavaScript: programming language for the whole application +* CSS: styling the user interface using [CSS Modules](https://github.com/css-modules/css-modules) +* [React](https://reactjs.org/): library for creating user interfaces with components +* [Redux](https://redux.js.org/): state and data flow handling +* [Final Form](https://github.com/final-form/final-form): forms +* [React Router](https://reacttraining.com/react-router/): routing +* [Express](https://expressjs.com/): server ## Setup @@ -99,8 +110,9 @@ This command will create `.env` file and guide you trough setting up the require variables. The `.env` file is the place to add your local configuration. It is ignored in Git, so you'll have to add the corresponding configuration also to your server environment. -There are some mandatory configuration variables that are defined in the template. See the -[Environment configuration variables](env.md) documentation for more information. +There are some mandatory configuration variables that are defined in the template. See the Flex Docs +[FTW Environment configuration variables](https://www.sharetribe.com/docs/references/ftw-env/) +reference for more information. See also the [src/config.js](../src/config.js) file for more configuration options. @@ -112,7 +124,7 @@ To develop the application and to see changes live, start the frontend developme **Known issues:** -- Adding/changing `import`s may not be synced properly with ESLint. You may see an error +* Adding/changing `import`s may not be synced properly with ESLint. You may see an error `Unable to resolve path to module` even though the module existing in right path. Restarting the server doesn't help. To solve the issue, you need to make a change to the file where the error occurs. diff --git a/docs/deploying-to-production.md b/docs/deploying-to-production.md index adfd7807..44fd4da7 100644 --- a/docs/deploying-to-production.md +++ b/docs/deploying-to-production.md @@ -28,11 +28,12 @@ To deploy the application add at least the following variables: | `PORT` | Must be set if the production environment doesn't set it by default. Not needed in Heroku. | | `REACT_APP_SHARETRIBE_SDK_CLIENT_ID` | Client ID (API key) you can check from [Flex Console](https://flex-console.sharetribe.com/login/). You will get this from the Sharetribe team. | | `REACT_APP_STRIPE_PUBLISHABLE_KEY` | Stripe publishable API key for generating tokens with Stripe API. It can be found from Stripe [API keys](https://dashboard.stripe.com/account/apikeys) page. Make sure to toggle _"View test data"_ on if you don't want to use real money yet. The secret key needs to be added to Flex Console. | -| `REACT_APP_MAPBOX_ACCESS_TOKEN` | Sign up for Mapbox and go to [account page](https://www.mapbox.com/account/access-tokens). Then click `Create access token`. For more information see the [Integrating to map providers](./map-providers.md) documentation. | +| `REACT_APP_MAPBOX_ACCESS_TOKEN` | Sign up for Mapbox and go to [account page](https://www.mapbox.com/account/access-tokens). Then click `Create access token`. See the Flex Docs [How to set up Mapbox for FTW](https://www.sharetribe.com/docs/guides/how-to-set-up-mapbox-for-ftw/) guide for more information. | | `REACT_APP_CANONICAL_ROOT_URL` | Canonical root URL of the marketplace. E.g. https://the-name-of-your-app.herokuapp.com or your actual domain. This is needed for social media sharing and SEO optimization. | -There are also some other variables that can be used. See the -[Enviroment configuration variables](./env.md) documentation for more information. +There are also some other variables that can be used. See the Flex Docs +[FTW Environment configuration variables](https://www.sharetribe.com/docs/references/ftw-env/) +reference for more information. ### Building the app @@ -51,13 +52,13 @@ Start the server: ## Deploying to Heroku -- [Forking the repository](#forking-the-repository) -- [Creating new app](#creating-new-app) -- [Connect GitHub to Heroku](#connect-github-to-heroku) -- [Heroku settings](#heroku-settings) - - [Updating enviroment variables](#updating-enviroment-variables) - - [Domains and certificates](#domains-and-certificates) -- [Heroku logs](#heroku-logs) +* [Forking the repository](#forking-the-repository) +* [Creating new app](#creating-new-app) +* [Connect GitHub to Heroku](#connect-github-to-heroku) +* [Heroku settings](#heroku-settings) + * [Updating enviroment variables](#updating-enviroment-variables) + * [Domains and certificates](#domains-and-certificates) +* [Heroku logs](#heroku-logs) Before creating the app you need three accounts: [Heroku](https://heroku.com/), [Stripe](https://stripe.com/fi) and [MapBox](https://www.mapbox.com/). Creating the accounts is free @@ -103,7 +104,7 @@ from any branch in the repository. Read more from Heroku docs: -- [GitHub Integration](https://devcenter.heroku.com/articles/github-integration) +* [GitHub Integration](https://devcenter.heroku.com/articles/github-integration) ### Heroku settings @@ -126,8 +127,8 @@ SSH settings in the _Settings tab_. Read more from Heroku docs: -- [Custom Domain Names for Apps](https://devcenter.heroku.com/articles/custom-domains) -- [Manually Acquiring an SSL/TLS Certificate](https://devcenter.heroku.com/articles/acquiring-an-ssl-certificate) +* [Custom Domain Names for Apps](https://devcenter.heroku.com/articles/custom-domains) +* [Manually Acquiring an SSL/TLS Certificate](https://devcenter.heroku.com/articles/acquiring-an-ssl-certificate) ![Heroku settings](./assets/deploying-to-production/heroku-domains.png) diff --git a/docs/env.md b/docs/env.md index c44650be..9fb906d2 100644 --- a/docs/env.md +++ b/docs/env.md @@ -1,42 +1,5 @@ # Environment configuration variables -The following configuration variables can be set to control the Flex template app behaviour. Most of -them have defaults that work for development environment. For production deploys most should be set. +Documentation moved to the Flex Docs site: -| Variable | Description | -| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| REACT_APP_MAPBOX_ACCESS_TOKEN | See: [Integrating to map providers](./map-providers.md) | -| REACT_APP_GOOGLE_MAPS_API_KEY | See: [Google Maps API key](./google-maps.md) (Alternative map provider) | -| REACT_APP_SHARETRIBE_SDK_CLIENT_ID | Client ID (API key). You can get this from the Flex Console. | -| REACT_APP_STRIPE_PUBLISHABLE_KEY | Stripe publishable API key for generating tokens with Stripe API. Use test key (prefix `pk_test_`) for development. The secret key needs to be added to Flex Console. | -| REACT_APP_SHARETRIBE_MARKETPLACE_CURRENCY | The currency used in the Marketplace as ISO 4217 currency code. For example: USD, EUR, CAD, AUD, etc. | -| REACT_APP_CANONICAL_ROOT_URL | Canonical root url of the marketplace. Needed for social media sharing and SEO optimization. | -| NODE_ENV | Node env. Use 'development' for development and 'production' for production. | -| PORT | Port for server to accept connections. | -| REACT_APP_ENV | A more fine grained env definition than NODE_ENV. Is used for example to differentiate envs in logging. | -| REACT_APP_SHARETRIBE_USING_SSL | Redirect HTTP to HTTPS? | -| SERVER_SHARETRIBE_TRUST_PROXY | Set when running the app behind a reverse proxy, e.g. in Heroku. | -| REACT_APP_SENTRY_DSN | See: [Error logging with Sentry](./sentry.md) | -| REACT_APP_CSP | See: [Content Security Policy (CSP)](./content-security-policy.md) | -| BASIC_AUTH_USERNAME | Set to enable HTTP Basic Auth | -| BASIC_AUTH_PASSWORD | Set to enable HTTP Basic Auth | -| REACT_APP_GOOGLE_ANALYTICS_ID | See: [Google Analytics](./analytics.md) | -| REACT_APP_AVAILABILITY_ENABLED | Enables availability calendar for listings. | -| REACT_APP_DEFAULT_SEARCHES_ENABLED | Enables default search suggestions in location autocomplete search input. | -| REACT_APP_SHARETRIBE_SDK_BASE_URL | The base url to access the Sharetribe Flex Marketplace API. FTW uses the correct one by default so no need to set this. | - -## Defining configuration - -When the app is started locally with `yarn run dev` or `yarn run dev-server`, you can set -environment variables by using the (gitignored) `.env` file. You can edit the basic variables via -`yarn run config` or by editing directly the .env file. Some variables can be edited only in the -.env file. The repository contains a template file `.env-template` with default configuration. - -In production, it's recommended that you set the configuration via env variables and do not deploy -an .env file. The client application will only be packaged with env variables that start with -REACT_APP. This way server secrets don't end up in client bundles. - -**With deploys note that the configuration options are bundled in the client package at build -time.** The configuration of the build environment must match run environment for things to work -consistently. To apply changes to configuration values client bundle must be rebuilt. Just -restarting the server is not enough. +https://www.sharetribe.com/docs/references/ftw-env/ diff --git a/docs/google-maps.md b/docs/google-maps.md index 340dac64..3c419796 100644 --- a/docs/google-maps.md +++ b/docs/google-maps.md @@ -1,181 +1,5 @@ # Google Maps -Flex Template for Web (FTW) offers out of the box support for Google Maps API for showing a map and -searching locations with search autocompletion. This document describes how to set up the API key -for the API requests to work properly. +Documentation moved to the Flex Docs site: -> Note: before making the change to Google Maps, you should consider if you are OK with their -> current pricing. There's a pricing calculator available in their -> [pricing page](https://cloud.google.com/maps-platform/pricing/). FTW's default map provider is -> Mapbox, which is often cheaper. -> [Learn more about how to use Mapbox or some other map provider instead of Google Maps](https://github.com/sharetribe/flex-template-web/blob/e6034c7690c095553f44092b032689cd6b6f7546/docs/map-providers.md). - -## Generate a Google Maps API key - -Go to the -[Google Maps JavaScript API V3 Reference](https://developers.google.com/maps/documentation/javascript/reference), -click on the "GET A KEY" button in the top bar, and follow the instructions. You can copy the given -key to your application now. - -## Enable Google Places API Web Service - -Follow the instructions in the -[Getting started](https://developers.google.com/maps/documentation/javascript/places#GetStarted) -section of the Places library documentation to enable using the Google Places API Web Service. Also -Maps Static API and Maps Javascript API need to be enabled. - -## Setup the application to use the API key - -The application uses the `REACT_APP_GOOGLE_MAPS_API_KEY` environment variable for the key value. For -local development, you can add the variable in the Gitignored `.env` file in the project root: - -``` -REACT_APP_GOOGLE_MAPS_API_KEY=my-key-here -``` - -## Setup common locations to reduce typing - -The location autocomplete-input in the landing page and the topbar can be configured to have -specific locations shown by default when the user focuses on the input and hasn't yet typed in any -searches. This reduces the typing required for common searches and also reduces the need to use -Google Map Places API that much. - -To use default searches, another environment variable needs to be set: - -``` -REACT_APP_DEFAULT_SEARCHES_ENABLED=true -``` - -The default locations have been described in file: -[src/default-location-searches.js](../src/default-location-searches.js). - -The same environment variable also shows "current location" suggestion, which will make the browser -to ask user's current location. This is a fast way to search listings nearby. You can specify -whether to use the current location from [config.js](../src/config.js). Search for variables: -`suggestCurrentLocation` and `currentLocationBoundsDistance`. - -## Change components: use Google Map versions instead of Mapbox - -If you wish to use Google Maps instead of Mapbox, you need to make some changes to FTW default -setup. - -### 1. Include Google Map script instead of Mapbox scripts - -Mapbox related scripts can be removed from index.html and instead use Google Map script described in -comments. - -_public/index.html:_ - -```html - - - - - -``` - -### 2. Searching with Google's geocoding API - -Location search aka LocationAutocompleteInput should use Google Map specific geocoder. The correct -import is written to the comments of LocationAutocompleteInput component. - -_src/components/LocationAutocompleteInput/LocationAutocompleteInputImpl.js:_ - -```js -import Geocoder, { GeocoderAttribution, CURRENT_LOCATION_ID } from './GeocoderMapbox'; -// import Geocoder, { GeocoderAttribution, CURRENT_LOCATION_ID } from './GeocoderGoogleMaps'; -``` - -Furthermore, Google Map states in their terms of service that Google logo needs to be visible when -using their geocoding service. It is available as a background image below the autocomplete -predictions. However, there needs to be enough padding for that logo. You can change the padding -through `marketplace.css`. - -_src/marketplace.css:_ - -```js -/* Google Maps needs 72px bottom padding to accommodate logo, Mapbox doesn't have one */ ---locationAutocompleteBottomPadding: 8px; -``` - -### 3. Show correct map on ListingPage (Map component) - -Google Map version (containing both static and dynamic maps) can be taken into use by importing -correct map subcomponent. - -_src/components/Map/Map.js:_ - -```js -import { StaticMap, DynamicMap, isMapsLibLoaded } from './MapboxMap'; -// import { StaticMap, DynamicMap, isMapsLibLoaded } from './GoogleMap'; -``` - -### 4. SearchMap.js - -The most complex change is happening in SearchPage. First, you need to import `SearchMapWithMapbox` -instead of `SearchMapWithGoogleMap`. - -_src/components/SearchMap/SearchMap.js:_ - -Remove this: - -```js -import SearchMapWithMapbox, { - LABEL_HANDLE, - INFO_CARD_HANDLE, - getMapBounds, - getMapCenter, - fitMapToBounds, - isMapsLibLoaded, -} from './SearchMapWithMapbox'; -``` - -And add this instead: - -```js -import SearchMapWithGoogleMap, { - LABEL_HANDLE, - INFO_CARD_HANDLE, - getMapBounds, - getMapCenter, - fitMapToBounds, - isMapsLibLoaded, -} from './SearchMapWithGoogleMap'; -``` - -Then, in `render` method, you need to put `SearchMapWithGoogleMap` component into use by replacing -`SearchMapWithMapbox` which is defined inside `ReusableMapContainer`. The component with correct -props is already there in the comments: - -```js -// When changing from default map provider to Google Maps, you should use the following -// component instead of SearchMapWithMapbox: -// -// -// } -// mapElement={
} -// bounds={bounds} -// center={center} -// location={location} -// infoCardOpen={infoCardOpen} -// listings={listings} -// activeListingId={activeListingId} -// mapComponentRefreshToken={this.state.mapReattachmentCount} -// createURLToListing={this.createURLToListing} -// onListingClicked={this.onListingClicked} -// onListingInfoCardClicked={this.onListingInfoCardClicked} -// onMapLoad={this.onMapLoadHandler} -// onMapMoveEnd={onMapMoveEnd} -// zoom={zoom} -// /> -``` - -The only extra step is to make `mapRootClassName` property available from `this.props` at the -beginning of the `render` method. +https://www.sharetribe.com/docs/guides/how-to-use-google-maps-in-ftw/ diff --git a/docs/map-providers.md b/docs/map-providers.md index d498bae8..37f9cd0c 100644 --- a/docs/map-providers.md +++ b/docs/map-providers.md @@ -1,82 +1,5 @@ # Integrating to map providers -Choice of map provider can significantly impact your costs. Flex Template for Web (FTW) originally -supported only [Google Maps](./google-maps.md) out of the box, but after Google increased the -pricing of its APIs a lot, the default provider was changed to Mapbox. The template now supports -both Mapbox and Google Maps, and the map library used by Mapbox is used also by several other map -providers, so integrating new providers that support this is rather easy (see instructions at the -end of this doc). +Documentation moved to the Flex Docs site: -## Setting up the Mapbox integration (the default map provider) - -### 1. Generate a Mapbox access token - -[Sign up for a Mapbox](https://www.mapbox.com/signup/) and go to the -[account page](https://www.mapbox.com/account/). Then copy the `Default public token`. - -If you prefer to create a new one, click `+ Create a token`, give it a name and make sure all Public -scopes are selected. Create the token and copy its value. - -> Read more about -> [access tokens and consider rotating them](https://www.mapbox.com/help/how-access-tokens-work/). - -### 2. Setup the application to use the access token - -The application uses the `REACT_APP_MAPBOX_ACCESS_TOKEN` environment variable for the token value. -For local development, you can add the variable in the Gitignored `.env` file in the project root: - -``` -REACT_APP_MAPBOX_ACCESS_TOKEN=my-access-token-here -``` - -### 3. Setup common locations to reduce typing - -The location autocomplete input in the landing page and the topbar can be configured to have -specific locations shown by default when the user focuses on the input and hasn't yet typed in any -searches. This reduces the typing required for common searches and also reduces the need to use -Mapbox geolocation API that much. - -This is enabled by default but it can be changed via the environment variable: - -``` -REACT_APP_DEFAULT_SEARCHES_ENABLED=true -``` - -The default locations are described in -[src/default-location-searches.js](../src/default-location-searches.js). - -The same environment variable also shows "current location" suggestion, which will make the browser -to ask user's current location. This is a fast way to search listings nearby. You can specify -whether to use the current location from [config.js](../src/config.js). Search for variables: -`suggestCurrentLocation` and `currentLocationBoundsDistance`. - -### 4. Check rare default configurations - -Mapbox geocoding API doesn't always return bounding boxes for locations. Without bounding box -SearchMap component can't adjust zoom level right for that particular place. Therefore there are -default bounding boxes defined to different place types in -[Mapbox specific geocoder](../src/components/LocationAutocompleteInput/GeocoderMapbox.js). - -### Optional: Restrict location autocomplete to specific country or countries - -If your marketplace works only in a specific country or countries it might be a good idea to limit -the location autocomplete to those countries. You can specify whether to use the limitation from -[config.js](../src/config.js). Search for variable `countryLimit` and uncomment the line to make it -active. Provide the country or countries in an array using -[ISO 3166 alpha 2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format (eg. GB, US, FI). If -there are multiple values, separate them with commas. - -## Changing the map providers - -### How to change from Mapbox to Google Maps - -It is possible to use Google Map instead of the default map provider. Read more from -[Google Map setup guide](./google-maps.md) - -### How to use other map providers - -The default map setup of FTW uses library called `mapbox-gl-js`. It is supported by quite many other -map providers too. Thus, if you wish to use a map provider other than Google Maps or Mapbox, first -check if the map provider you are considering is supporting this library. If they are, the change -might be quite easy. Note: if you change the map tile provider you should also change geocoding API -too (i.e. the API endpoint for `LocationAutocompleteInput` component). +https://www.sharetribe.com/docs/guides/how-to-set-up-mapbox-for-ftw/ diff --git a/docs/routing.md b/docs/routing.md index aea13b59..8e93703d 100644 --- a/docs/routing.md +++ b/docs/routing.md @@ -7,11 +7,11 @@ instead of defining on server-side what gets rendered when user goes to URL `somemarketplace.com/about`, we just catch all the path combinations and let the app to define what page gets rendered. -- [React Router setup](#react-router-setup) -- [Linking](#linking) -- [Loading data](#loading-data) -- [Analytics](#analytics) -- [A brief introduction to server-side rendering](#a-brief-introduction-to-ssr) +* [React Router setup](#react-router-setup) +* [Linking](#linking) +* [Loading data](#loading-data) +* [Analytics](#analytics) +* [A brief introduction to server-side rendering](#a-brief-introduction-to-ssr) ## React Router setup @@ -144,11 +144,13 @@ const Routes = (props, context) => { Inside `src/Routes.js`, we also have a component called `RouteComponentRenderer`, which has three important jobs: -- Calling loadData function, if those have been defined in `src/routeConfiguration.js`. This is an +* Calling loadData function, if those have been defined in `src/routeConfiguration.js`. This is an asynchronous call, a page needs to define what gets rendered before data is complete. -- Reset scroll position after location change. -- Dispatch location changed actions to Redux store. This makes it possible for - [analytics Redux middleware](analytics.md) to listen location changes. +* Reset scroll position after location change. +* Dispatch location changed actions to Redux store. This makes it possible for analytics Redux + middleware to listen location changes. For more information, see the + [How to set up Analytics for FTW](https://www.sharetribe.com/docs/guides/how-to-set-up-analytics-for-ftw/) + guide in Flex Docs. ## Linking @@ -227,7 +229,9 @@ It is possible to track page views to gather information about navigation behavi tied to routing through `src/Routes.js` where `RouteRendererComponent` dispatches `LOCATION_CHANGED` actions. These actions are handled by a global reducer (`src/ducks/Routing.duck.js`), but more importantly, `src/analytics/analytics.js` (a Redux middleware) listens to these changes and sends -tracking events to configured services. [Read more.](analytics.md) +tracking events to configured services. For more information, see the +[How to set up Analytics for FTW](https://www.sharetribe.com/docs/guides/how-to-set-up-analytics-for-ftw/) +guide in Flex Docs. ## A brief introduction to SSR diff --git a/docs/sentry.md b/docs/sentry.md index d4b186dc..537134d5 100644 --- a/docs/sentry.md +++ b/docs/sentry.md @@ -1,37 +1,5 @@ # Error logging with Sentry -The Flex template application supports error logging with [Sentry](https://sentry.io/) out of the -box provided that required environment variables are set in place. Other logging solutions can also -be used but the Sentry client comes already strapped into application. +Documentation moved to the Flex Docs site: -## Setting up Sentry keys - -To enable the Sentry error logging a DSN, _Data Source Name_ has to be provided as an environment -variable. Browser and Node environments use both the same key: - -- **REACT_APP_SENTRY_DSN** - -The DSN key can be aquired from the Sentry project settings. To test it in your local environment it -can be passed for example to the `yarn run dev-server` command: - - REACT_APP_SENTRY_DSN='' yarn run dev-server - -If the Sentry DSN key is not provided the template app will log errors to the console. The logging -and Sentry setup is implemented in [util/log.js](../src/util/log.js) and -[server/log.js](../server/log.js) so refer to those files to change the external logging service or -the logging logic in general. - -## Source map retrieval - -By default Sentry fetches the source maps for minified javascript files. However, this might now -work in case some sort of authentication, e.g. basic auth, is required to reach your application. To -circumvent this a security token can be configured to Sentry. Sentry then adds this token to the -source maps request header so that the server hosting the marketplace can then be configured to let -those requests access the source maps. - -For basic auth the security token can be configured as follows: - -In _Project > Settings > General > Client Security_ set the following values - -- **Security token** - `Basic ` -- **Security token header** - `Authorization` +https://www.sharetribe.com/docs/guides/how-to-set-up-sentry-to-log-errors-in-ftw/