Skip to content

README: Creates a table, minor changes, and moderate re-organization. #2

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

Merged
merged 1 commit into from
Aug 20, 2018
Merged

README: Creates a table, minor changes, and moderate re-organization. #2

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 33 additions & 33 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,23 +3,21 @@
The Reference UI is a configurable, generic UI meant to work with
any [App Search](https://www.elastic.co/cloud/app-search-service) Engine. It
can serve as a simple demo, a functional test for your Engine data,
and also a code reference to use when building out your own App Search
or as a code reference when building out your own App Search
UI.

The project can be configured via a JSON [config file](src/config/engine.json),
which allows you to easily control things like:
which allows you to easily control things like...

- What Engine this UI runs against
- What fields are displayed
- What filters are used
- The Engine the UI runs against
- Which fields are displayed
- The filters that are used

A complete list of configuration options can be found [below](#config).
The README assumes that you have generated this code from within the App Search dashboard.

## Setup

### If you just downloaded this via the Dashboard

You'll need to install [npm](https://www.npmjs.com/). Once you have "npm"
You will need to install [npm](https://www.npmjs.com/). Once you have "npm"
installed, you should be able to use the `npm` command from within your
terminal.

Expand All @@ -38,16 +36,38 @@ npm install
npm start
```

#### Updating configuration
### Updating configuration

If you would like to make configuration changes, there is no need to regenerate
this app from your App Search Dashboard! You can simply open up the
[engine.json](src/config/engine.json) file, update the [options](#config),
and restart this app.
and then restart this app.

### Configuration options <a id="config"></a>

The following is a complete list of options available for configuration in [engine.json](src/config/engine.json).

| option | value type | required/optional | source
| --- | --- | --- | --- |
| `engineName` | String | required | Found in your [App Search Dashboard](http://app.swiftype.com/as). |
| `hostIdentifier` | String | required | Found in your [App Search Dashboard](http://app.swiftype.com/as). |
| `searchKey` | String | required | Found in your [App Search Dashboard](http://app.swiftype.com/as). |
| `fields` | Array[String] | required | A list of fields that will be searched and displayed within your results. |
| `titleField` | String | optional | The field to display as the title in results. |
| `urlField` | String | optional | A field with a url to use as a link in results. |
| `urlFieldTemplate` | String | optional | Instead of urlField, you can provide a URL "template" here, which lets you build a URL from other fields. ex: "https://www.example.com/{{id}}". |
| `sortFields` | Array[String] | required | A list of fields that will be used for sort options. |
| `facets` | Array[String] | required | A list of fields that will be available as "facet" filters. Read more about facets within the [App Search documentation](https://swiftype.com/documentation/app-search/guides/facets). |

### External configuration

If you are embedding this app inside of another page, and you would like to
source the configuration from outside of the `engine.json` file,
you can simply write the configuration directly to `window.appConfig`.

### If you're checking this project out directly from github
### If you are checking this project out directly from GitHub... <a id="github"></a>

Follow the previous steps, but you'll also need to configure
You can follow the previous steps, but then you will need to configure
[engine.json](src/config/engine.json).

To do so, make a copy of [engine.json.example](src/config/engine.json.example),
Expand All @@ -56,23 +76,3 @@ rename it to `engine.json` and configure with your Engine's specific details.
```bash
cp src/config/engine.json.example src/config/engine.json
```

## Configuration options <a id="config"></a>

The following is a complete list of options available for configuraiton in [engine.json](src/config/engine.json).

- engineName - (String) Found in your [App Search Dashboard](http://app.swiftype.com/as)
- hostIdentifier - (String) Found in your [App Search Dashboard](http://app.swiftype.com/as)
- searchKey - (String) Found in your [App Search Dashboard](http://app.swiftype.com/as)
- fields - (Array[String]) A list of fields that will be searched, and also displayed in results
- titleField - (String)(Optional) The field to display as the title in results
- urlField - (String)(Optional) A field with a url to use as a link in results
- urlFieldTemplate - (String)(Optional) Instead of urlField, you can provide a URL "template" here, which lets you build a URL from other fields. ex: "http://www.example.com/{{id}}"
- sortFields - (Array[String]) A list of fields that will be used for sort options
- facets - (Array[String]) A list of fields that will be available as "facet" filters

## External configuration

If you are embedding this app inside of another page, and you'd like to
source the configuration from outside of the `engine.json` file,
you can simply write the configuration directly to `window.appConfig`.