npm package: @flexdemo/guides-react
Description: A Component that will display guides as part of a documentation
Author: Sebastian Venhuis
Latest version: 0.0.12

# Guides React

A React component that will render small help guides.

## Quickstart

```javascript
import { Guides } from "guides-react";
//...
<App>
  <Guides logo={<h1>Some Awesome Logo</h1>} footer={<span>Imprint</span>} placeholder={"Search"} />
</App>;
//...
```

## Examples

### Basic usage

1. Install and start the guides-backend server
2. Include component in your app

```javascript
import { Guides } from "guides-react";
//...
<App>
  <Guides logo={<h1>Some Awesome Logo</h1>} footer={<span>Imprint</span>} placeholder={"Search"} />
</App>;
//...
```

3. Build your App with `REACT_APP_GUIDES_API_URL` Environment Variable set to the appropriate Backend URL

### Usage without a Server

```javascript
import { Guides } from "guides-react";
const guides = [
  {
    internalName: "guide_1.md",
    content:
      "# Usage without a Server\nUsing guides-react without a server is fairly simple, but writing and inserting guides is not very confortable",
  },
];
//...
<App>
  <Guides logo={<h1>Some Awesome Logo</h1>} footer={<span>Imprint</span>} placeholder={"Search"} guides={guides} />
</App>;
```

### Storybook

This component contains Storybook examples. To run the Storybook clone the repository and run `npm run storybook`.

> Do note, that the Storybook requires differently prefixed environment variables, as `REACT_APP_*` variables do not work. All environment variables can also be provided with the `STORYBOOK_` prefix. For example `REACT_APP_GUIDES_API_URL` can also be provided with `STORYBOOK_GUIDES_API_URL`
> .

## Backend

This component is designed to work with the guides-backend server, which can be used to supply the guides and provide a indexed search of these guides.

It is also possible to use a custom Backend, or no backend at all. See the examples for further information.

### Response Timeouts
This library tracks likes and dislikes for documents, but only in a **very** limited fashion. No use accounts are necessary, but to prevent abuse of the likes and dislikes a timeout can be set in which the same document can not be likes or disliked again. By default this timeout is 5 Minutes, but it can be changed by setting the ```REACT_APP_GUIDES_RESPONSE_TIMEOUT``` variable to a string like `5M` or `30S`. See [moment.js](https://momentjs.com/docs/#/durations/creating/) for more information uon duration parsing. (The "PT" is appended by default)

### Custom backend

It is also fairly easy to implement the required backend routs yourself, this section will describe the required routes, parameters and results.

#### /docs [GET]

Requests a List of all available documents.

_Parameters_: None

_Result_:

| Name             | Value                                                                                                                                                             |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-Type     | application/json                                                                                                                                                  |
| Return Code      | 200                                                                                                                                                               |
| Expected Content | [{<br/>filename: string // the full name of the file (relativ to the backend server <br/>key: string //The name of the file without any prefix or suffix <br/> }] |

> _Note_: This route can be redirected by setting the `REACT_APP_GUIDES_DOCS_ROUTE` environment variable to the appropriate route. The default is `docs` (no / prefix)

#### /search/:query [GET]

Requests a List of all available documents that match the given query.

_Parameters_:

| Name  | Type   | value                   |
| ----- | ------ | ----------------------- |
| query | string | The query to search for |

_Result_:

| Name             | Value                                                                                                                                                                                                                                         |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Content-Type     | application/json                                                                                                                                                                                                                              |
| Return Code      | 200                                                                                                                                                                                                                                           |
| Expected Content | [{<br/>filename: string // the full name of the file (relativ to the backend server <br/>key: string //The name of the file without any prefix or suffix <br/>count: number // value for ranking the result -> the higher the better <br/> }] |

> _Note_: This route can be redirected by setting the `REACT_APP_GUIDES_SEARCH_ROUTE` environment variable to the appropriate route. The default is `search` (no / prefix)

#### /document uri [GET]

Requests the content of the document. The exact URL depends on the result of the /docs query, more specific on the `filename` field.

_Parameters_: None

_Result_:

| Name         | Value |
| ------------ | ----- |
| Content-Type | text  |
| Return Code  | 200   |

#### /like/doc_key and /dislike/doc_key [POST]

Likes or dislikes to specified document. The values of these likes and dislikes do not need to be public. They mainly serve the purpose of giving the document writer feedback over good and bad documents.

> _Note_: These routes can be redirected by setting the `REACT_APP_GUIDES_LIKE_ROUTE` or `REACT_APP_GUIDES_DISLIKE_ROUTE` environment variable to the appropriate route. The default is `like` and `dislike` (no / prefix or /doc_key postfix)

_Parameters_:

| Name    | Type | value                               |
| ------- | ---- | ----------------------------------- |
| doc_key | url  | The key returned by the /docs route |

_Result_:

| Name         | Value |
| ------------ | ----- |
| Content-Type | text  |
| Return Code  | 200   |