flex-template-web/docs/README.md

# Flex Template for Web: Documentation

## Why Saunatime?

_Short answer:_ Demonstrate the features of Flex with a marketplace for renting saunas. Because why
not.

_Long answer:_ Saunatime works as a template for a marketplace user interface. It can be used as a
marketplace client out of the box but is intended to be modified to match the requirements of each
marketplace built on top of the Flex API. Also, marketplaces that do not use Saunatime as a template
for building a client can use this template application as a reference on how the Flex API can be
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
  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.

## Directory structure

After cloning the repo, your project should look like this:

```
├── ext/
│   └── default-mail-templates/
├── package.json
├── docs/
├── public/
│   ├── static/
│   ├── 500.html
│   ├── index.html
│   └── robots.txt
├── server/
│   ├── csp.js
│   ├── index.js
│   ├── sitemap.js
│   └   ...
└── src/
    ├── analytics/
    ├── assets/
    ├── components/
    ├── containers/
    ├── ducks/
    ├── forms/
    ├── translations/
    ├── util/
    ├── Routes.js
    ├── app.js
    ├── config.js
    ├── examples.js
    ├── index.js
    ├── marketplace-custom-config.js
    ├── marketplace.css
    ├── marketplaceFonts.css
    ├── marketplaceIndex.css
    ├── reducers.js
    ├── routeConfiguration.js
    └── store.js
```

### public/index.html

This is the page template. It includes fonts, Stripe SDK, Mapbox API (and Google Maps JavaScript
API), and app icons. It also specifies placeholders for tags generated by
[React Helmet](https://github.com/nfl/react-helmet)

### src/

- `src/index.js` is the JavaScript entry point on the client-side (it also exports `renderApp`
  function to be used for server-side rendering).
- `src/app.js` creates ClientApp and ServerApp
- `src/routeConfiguration.js` defines logic between routes and page-level components
- `src/marketplace.css`, `src/marketplaceIndex.css`, `src/marketplaceIndex.css` define marketplace
  level styling using [CSS Properties](http://cssnext.io/features/#custom-properties-var) and CSS
  Property Sets.
- `src/translations/en.json` all English translations used in Saunatime template app. (A good place
  to start customization.)

#### `src/components/`

Normal components used in Flex Template for Web are defined here. The main file for the component is
behind path `src/components/ComponentName/ComponentName.js`, but you can import it through
`component/index.js`:

`import { NamedLink } from 'path/to/components';`

When creating new components, remember to import marketplace.css file to component's own CSS file -
that way you can use CSS Property variables defined in `src/marketplace.css`.

#### `src/containers/`

Containers are components that are connected to [Redux](https://redux.js.org/) store. Currently,
this folder contains only page-level components and one common component: TopbarContainer.

#### `src/forms/`

Forms are in their own folder since they are using a special library to handle validations, errors,
internal state, etc.

### server/

- `server/index.js` handles server-side rendering (SSR). Built with [Express](http://expressjs.com)
  (Node.js framework).
- `server/csp.js` [Content Security Policy](https://content-security-policy.com), whitelist of
  domains that the application and loaded scripts are allowed to access from the browser.
- `server/sitemap.js` generates a minimal sitemap.xml for SEO purposes.

### ext/default-mail-templates/

This directory contains default email templates for transaction-specific needs (e.g.
_booking-request-accepted_). However, there are some built-in email templates that you can change in
[Flex Console](http://flex-console.sharetribe.com/email-templates/email-changed).

_**NOTE:** Changing these doesn't change actual email templates - you need to send customized
templates to your Flex contact person._

## 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/)

## Customization guide

The easiest way to start a customization project is to read through the
[How to Customize FTW](https://www.sharetribe.com/docs/guides/how-to-customize-ftw/) guide in Flex
Docs.

## How to customize this template

After going through the customization guide, you should probably start with the following guides in
Flex Docs:

- [How to set up Mapbox for FTW](https://www.sharetribe.com/docs/guides/how-to-set-up-mapbox-for-ftw/)
- [How to change FTW UI texts and translations](https://www.sharetribe.com/docs/guides/how-to-change-ftw-ui-texts-and-translations/)
- [How to customize FTW styles](https://www.sharetribe.com/docs/guides/how-to-customize-ftw-styles/)
- [How to change Terms of Service and Privacy Policy in FTW](https://www.sharetribe.com/docs/guides/how-to-change-tos-and-privacy-policy-in-ftw/)
- [How to change FTW icons](https://www.sharetribe.com/docs/guides/how-to-change-ftw-icons/)
- [FTW customization checklist](https://www.sharetribe.com/docs/guides/ftw-customization-checklist/)
- [How to deploy FTW to production](https://www.sharetribe.com/docs/guides/how-to-deploy-ftw-to-production/)
- [How routing works in FTW](https://www.sharetribe.com/docs/background/ftw-routing/)
- [How the Redux setup works in FTW](https://www.sharetribe.com/docs/background/ftw-redux/)

See also the following articles:

- [How to extend listing data in FTW](https://www.sharetribe.com/docs/guides/how-to-extend-listing-data-in-ftw/)
- [How to change search filters in FTW](https://www.sharetribe.com/docs/guides/how-to-change-search-filters-in-ftw/)
- [How to add static pages in FTW](https://www.sharetribe.com/docs/guides/how-to-add-static-pages-in-ftw/)
- [How to test FTW](https://www.sharetribe.com/docs/guides/how-to-test-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/)
- [How to use CI with FTW](https://www.sharetribe.com/docs/guides/how-to-use-ci-with-ftw/)
- [How to improve performance](https://www.sharetribe.com/docs/guides/how-to-improve-performance/)

See also the
[original create-react-app documentation](https://github.com/sharetribe/create-react-app/blob/master/packages/react-scripts/template/README.md).

The application was bootstrapped with a forked version of
[create-react-app](https://github.com/facebookincubator/create-react-app). While most of the
original documentation still applies, there are some important differences listed in the
[sharetribe-scripts](https://www.npmjs.com/package/sharetribe-scripts) NPM package.