A configurable, generic search UI for any Elastic App Search Engine.

Contents

• Getting started
• Usage
• FAQ
• Contribute
• License

---

Getting started 🐣

The Reference UI is great for:

• search demos
• functional tests of App Search Engine data
• a starting point for new search experiences

Requires npm.

Dependencies:

• Node v16.13.0

One can leverage NVM to install Node before proceeding to start the application by running the following commands:

# Run this to install Node 16.13.0
nvm install 16.13.0

# Run this to use the installed Node version 
nvm use 16.13.0

The README assumes that you have generated this code from within the App Search dashboard.

Run the following commands to start this application:

# Run the `cd` command to change the current directory to the
# location of your downloaded Reference UI. Replace the path
# below with the actual path of your project.
cd ~/Downloads/app-search-reference-ui

# Run this to set everything up
npm install

# Run this to start your application and open it up in a new browser window
npm start

Usage

Updating configuration

The project can be configured via a JSON config file.

You can easily control things like...

• The Engine the UI runs against
• Which fields are displayed
• The filters that are used

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 file, update the options, and then restart this app.

Configuration options

The following is a complete list of options available for configuration in engine.json.

option	value type	required/optional	source
engineName	String	required	Found in your App Search Dashboard.
endpointBase	String	required*	(*) Elastic Enterprise Search deployment URL, example: "http://127.0.0.1:3002". Not required if using App Search on swiftype.com.
hostIdentifier	String	required*	(*) Only required if using App Search on swiftype.com.
searchKey	String	required	Found in your App Search Dashboard.
searchFields	Array[String]	required	A list of fields that will be searched with your search term.
resultFields	Array[String]	required	A list of fields that will be displayed within your results.
querySuggestFields	Array[String]	optional	A list of fields that will be searched and displayed as query suggestions.
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.
sortFields	Array[String]	optional	A list of fields that will be used for sort options.
facets	Array[String]	optional	A list of fields that will be available as "facet" filters. Read more about facets within the App Search documentation.

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 are checking this project out directly from GitHub...

You can follow the previous steps, but then you will need to configure engine.json.

To do so, make a copy of engine.json.example, rename it to engine.json and configure it with your Engine's specific details.

cp src/config/engine.json.example src/config/engine.json

Deploy and Share

This app can be easily published to any server as static assets and served. We recommend Netlify, but you have other options as well.

To deploy:

npm run build-js
npm install netlify-cli -g
netlify deploy # enter ./build as the deploy path

You'll then simply follow the command prompt to log into Netlify and deploy your site. This can be completed in just a few minutes.

Customization

This project is built with Search UI, which is a React library for building search experiences. If you're interested in using this project as a base for your own, most of what you'll need can be found in the Search UI documentation.

FAQ 🔮

Where do I report issues with the Reference UI?

If something is not working as expected, please open an issue.

Where can I learn more about App Search?

Your best bet is to read the documentation.

Where else can I go to get help?

You can checkout the Elastic App Search community discuss forums.

Contribute 🚀

We welcome contributors to the project. Before you begin, a couple notes...

• Before opening a pull request, please create an issue to discuss the scope of your proposal.
• Please write simple code and concise documentation, when appropriate.

License 📗

Apache-2.0 © Elastic

Thank you to all the contributors!