Guides React

A React component that will render small help guides.

Quickstart

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

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

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 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 | [{filename: string // the full name of the file (relativ to the backend server key: string //The name of the file without any prefix or suffix }] |

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 | [{filename: string // the full name of the file (relativ to the backend server key: string //The name of the file without any prefix or suffix count: number // value for ranking the result -> the higher the better }] |

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 |