Skip to content

Commit

Permalink
docs: write "getting started" (#415)
Browse files Browse the repository at this point in the history 
* docs(website): bootstrap new doc structure

* docs(website): add doc for `createAlgoliaInsightsPlugin`

* docs(website): add draft sections

* docs: rewrite "Integrating keyboard navigation" (#389)

* docs: rewrite "Accessing data with Context" (#390)

* docs: rewrote "Controlling behavior with State" (#391)

* docs: rewrite "Populating autocomplete with Sources" (#396)

* docs: write "Displaying items with Templates" (#397)

* fix(core): update query conditions

* chore(test): add tests for getEnvironmentProps onTouchMove (#398)

* feat(emptyStates): implements empty source template and renderEmpty method (#395)

* Implements `empty` template and `renderEmpty` method

* Add wait function to `test/utils` folder

Co-authored-by: François Chalifour <[email protected]>

* Add tests for `onActive` and `onSelect` on plugins (#400)

* feat(js): change renderer implementation to virtual DOM (#381)

* feat(js): change renderer implementation to virtual DOM

* feat(highlighting): revamp highlighting system to VDOM (#399)

* fix: fix code example (#403)

* docs: switch core usage with autocomplete-js (#401)

* docs: write "Basic configuration options" (#402)

* docs: write "help and discussion" page (#394)

* docs: add help page

* Apply suggestions from code review

Co-authored-by: François Chalifour <[email protected]>

Co-authored-by: François Chalifour <[email protected]>

* feat: getting started first draft

* Apply suggestions from code review

Co-authored-by: François Chalifour <[email protected]>

* feat: update code example

* fix: copy-edit

* feat: add placeholders

* fix: remove unnecessary code snippets

* fix: links

* fix: add record example

* fix: rename titles to be more user focused

* fix: correct URL

* fix: update links

* Apply suggestions from code review

Co-authored-by: Sarah Dayan <[email protected]>

* fix: update installation headers and add note

* fix: remove headless installation and add 3rd party caveat

* Update packages/website/docs/getting-started.md

Co-authored-by: François Chalifour <[email protected]>

* fix: remove CDNJS

* Update packages/website/docs/getting-started.md

Co-authored-by: François Chalifour <[email protected]>

* Update packages/website/docs/getting-started.md

* Update packages/website/docs/getting-started.md

Co-authored-by: Sarah Dayan <[email protected]>

* feat: add AutocompleteExample

* fix: merge docs-1

Co-authored-by: François Chalifour <[email protected]>
Co-authored-by: Sarah Dayan <[email protected]>
Co-authored-by: Yannick Croissant <[email protected]>
Co-authored-by: Clément Vannicatte <[email protected]>
Co-authored-by: François Chalifour <[email protected]>
  • Loading branch information
@francoischalifour @sarahdayan @shortcuts
6 people authored Feb 4, 2021
1 parent 48fc7da commit e75218b
Showing 1 changed file with 301 additions and 47 deletions.
348 changes: 301 additions & 47 deletions packages/website/docs/getting-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,76 +2,330 @@
id: getting-started
title: Getting Started
---
import { AutocompleteExample } from '@site/src/components/AutocompleteExample';
import { AutocompleteDocSearchItem } from '@site/src/components/AutocompleteDocSearchItem';
import { getAlgoliaHits } from '@algolia/autocomplete-js';
import algoliasearch from 'algoliasearch/lite';
const searchClient = algoliasearch(
'BH4D9OD16A',
'a5c3ccfd361b8bcb9708e679c43ae0e5'
);

:::note Draft
Get started with Autocomplete by building an Algolia search experience.

This page needs to cover:
This documentation offers a few ways to learn about the Autocomplete library:
- Read the [**Core Concepts**](basic-options) to learn more about underlying principles, like [**Sources**](sources) and [**State**](state).
- Follow the [**Guides**](using-query-suggestions-plugin) to understand how to build common UX patterns.
- Refer to [**API reference**](api) for a comprehensive list of parameters and options.
- Try out the [**Playground**](https://codesandbox.io/s/github/algolia/autocomplete.js/tree/next/examples/js?file=/app.ts) where you can fork a basic implementation and play around.

- These docs provide a few ways to learn how to use Autocomplete:
- Read about **Core Concepts**—here you can learn more about underlying principles, like **Sources** and **State**.
- Follow our **Guides** to understand how to build common UX patterns.
- Refer to **API reference**.
- [Maybe v2] Play in the **Playground** where you can select components of your autocomplete and we provide you with the code.
- Keep reading for a simple sample implementation
- Installation
- JS
- Core
- A basic example
- Commented code snippet on a basic example (only using query-suggestions plug-in) with resulting UI and links to various **Core Concepts.**

:::

This page is an overview of the Autocomplete documentation and related resources.

Autocomplete is a JavaScript library for **building autocomplete search experiences**.

## Features

- Displays suggestions as you type
- Provides autocompletion
- Supports custom templates for UI flexibility
- Works well with RTL languages
- Triggers custom hooks to plug your logic
- Plugs easily to Algolia's realtime search engine

## What is Autocomplete
Keep reading to see how to install Autocomplete and build a basic implementation with Algolia.

## Installation

Autocomplete is available on the [npm](https://www.npmjs.com/) registry.
The recommended way to get started is with the [`autocomplete-js`](autocomplete-js) package. It includes everything you need to render a JavaScript autocomplete experience.

### JavaScript
Otherwise, you can install the [`autocomplete-core`](createAutocomplete) package if you want to [build a renderer](creating-a-renderer) from scratch.

All Autocomplete packages are available on the [npm](https://www.npmjs.com/) registry.

```bash
yarn add @algolia/autocomplete-js@alpha
# or
npm install @algolia/autocomplete-js@alpha
```

If you do not wish to use a package manager, you can use standalone endpoints:
If you don't want to use a package manager, you can use a standalone endpoint:

```html
<!-- jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-js@alpha"></script>
```

We recommend using jsDeliver but [`autocomplete-js`](autocomplete-js) is also available through [unpkg](https://unpkg.com/@algolia/autocomplete-js@alpha).

:::note

We don't provide support regarding third party services like jsDeliver or other CDNs.

:::

## Defining where to put your autocomplete

<!-- unpkg -->
<script src="https://unpkg.com/@algolia/autocomplete-js@alpha"></script>
To get started, you need a container for your autocomplete to go in. If you don't have one already, you can insert one into your markup:

```js title="HTML"
<div id="autocomplete"></div>
```

### Headless
Then, insert your autocomplete into it by calling the [`autocomplete`](autocomplete-js) function and providing the [`container`](autocomplete-js/#container). It can be a [CSS selector](https://developer.mozilla.org/docs/Web/CSS/CSS_Selectors) or an [Element](https://developer.mozilla.org/docs/Web/API/HTMLElement).

```bash
yarn add @algolia/autocomplete-core@alpha
# or
npm install @algolia/autocomplete-core@alpha
Make sure to provide a container (e.g., a `div`), not an `input`. Autocomplete generates a fully accessible search box for you.

```js title="JavaScript"
import { autocomplete } from '@algolia/autocomplete-js';

autocomplete({
container: '#autocomplete',
placeholder: 'Search the autocomplete documentation',
openOnFocus: true,
getSources() {
return [];
},
});
```

If you do not wish to use a package manager, you can use standalone endpoints:
You may have noticed three new options: [`placeholder`](autocomplete-js#placeholder), [`openOnFocus`](autocomplete-js#openonfocus), and [`getSources`](sources#getsources).

```html
<!-- jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/@algolia/autocomplete-core@alpha"></script>
The [`placeholder`](autocomplete-js#placeholder) option defines the placeholder text to show until the user starts typing in the input, while the [`openOnFocus`](autocomplete-js#openonfocus) option determines whether to open the panel on [focus](https://developer.mozilla.org/en-US/docs/Web/API/Window/focus_event) or not, even when there's no query. It defaults to `false`, so you need to set it to `true` if you want the dropdown to appear as soon as a user clicks on it.

Autocomplete is now plugged in. But you won't see anything appear until you define your [sources](sources).

## Defining what items to display

[Sources](sources) define where to retrieve the items to display in your autocomplete dropdown. You define your sources in the [`getSources`](sources#getsources) function by returning an array of [source objects](sources#source). Each source object needs to include a [`getItems`](sources#getitems) function that returns the items to display. Sources can be static or dynamic.

This example uses the [Algolia index](https://www.algolia.com/doc/faq/basics/what-is-an-index/) [powering the documentation search](https://docsearch.algolia.com/) on this site as a source. The [`autocomplete-js`](autocomplete-js) package provides a built-in [`getAlgoliaHits`](getAlgoliaHits) function for just this purpose.

```js title="JavaScript"
import algoliasearch from 'algoliasearch/lite';
import { autocomplete, getAlgoliaHits } from '@algolia/autocomplete-js';

<!-- unpkg -->
<script src="https://unpkg.com/@algolia/autocomplete-core@alpha"></script>
const searchClient = algoliasearch(
'BH4D9OD16A',
'a5c3ccfd361b8bcb9708e679c43ae0e5'
);

autocomplete({
container: '#autocomplete',
placeholder: 'Search documentation',
openOnFocus: true,
getSources({ query }) {
return [
{
getItems() {
return getAlgoliaHits({
searchClient,
queries: [
{
indexName: 'autocomplete',
query,
params: {
hitsPerPage: 10
}
}
]
});
},
}
];
}
});
```

The preset requires an [Algolia search client](https://www.algolia.com/doc/api-client/getting-started/install/javascript/) initialized with an [Algolia application ID and API key](https://www.algolia.com/doc/guides/sending-and-managing-data/send-and-update-your-data/how-to/importing-with-the-api/#application-id). It lets you search into your Algolia index using an array of `queries`, which defines one or more queries to send to the index.

This example makes just one query to the "autocomplete" index using the `query` from [`getSources`](sources#getsources). It passes one additional parameter, [`hitsPerPage`](https://www.algolia.com/doc/api-reference/api-parameters/hitsPerPage/) to define how many items to display, but you could pass any other [Algolia query parameters](https://www.algolia.com/doc/api-reference/api-parameters/).

Although you've now declared what items display using [`getSources`](sources#getsources), you still won't see anything until you've defined _how_ to display the items you've retrieved.

## Defining how to display items

[Sources](sources) also define how to display items in your Autocomplete using [`templates`](templates). Templates can return a string or anything that's a valid Virtual DOM element. The example creates a [Preact](https://preactjs.com/) component called `AutocompleteItem` as the template for each item to display.

```jsx title="JSX"
/** @jsx h */
import { autocomplete, getAlgoliaHits } from '@algolia/autocomplete-js';
import algoliasearch from 'algoliasearch';
import { h } from 'preact';

const searchClient = algoliasearch(
'BH4D9OD16A',
'a5c3ccfd361b8bcb9708e679c43ae0e5'
);

function AutocompleteItem({ hit, breadcrumb }) {
return (
<a href={hit.url} className="aa-ItemLink">
<div className="aa-ItemContent">
<div className="aa-ItemTitle">{hit.hierarchy[hit.type]}</div>
<div className="aa-ItemContentSubtitle">{breadcrumb.join(' • ')}</div>
</div>
</a>
);
}

autocomplete({
container: '#autocomplete',
placeholder: 'Search documentation',
openOnFocus: true,
getSources({ query }) {
return [
{
getItems() {
return getAlgoliaHits({
searchClient,
queries: [
{
indexName: 'autocomplete',
query,
params: {
hitsPerPage: 10,
},
},
],
});
},
templates: {
item({ item }) {
return AutocompleteItem({
hit: item,
breadcrumb: Object.values(item.hierarchy)
.filter(Boolean)
.slice(0, -1),
});
},
},
},
];
},
});
```

The template displays the section name from the deepest level of `item.hierachy`. Beneath that, it displays a breadcrumb from all the higher levels in `item.hierarchy`.

This is what the JSON record looks like:

```json title="JSON record"
{
"hierarchy": {
"lvl0": "The Basics",
"lvl1": "Getting Started",
"lvl2": "Defining how to display items",
"lvl3": null,
"lvl4": null,
"lvl5": null,
"lvl6": null
},
"type": "lvl2",
"url": "https://autocomplete.algolia.com/docs/getting-started/"
}
```

Check out how the template displays items by searching in the input below:

<AutocompleteExample
getSources={({ query }) => {
return [
{
getItems() {
return getAlgoliaHits({
searchClient,
queries: [
{
indexName: 'autocomplete',
query,
params: {
hitsPerPage: 5
}
}
]
});
},
templates: {
item({ item }) {
return (
<AutocompleteDocSearchItem
hit={item}
breadcrumb={Object.values(item.hierarchy)
.filter(Boolean)
.slice(0, -1)}
/>
);
}
},
},
];
}}
/>

This is all you need for a basic implementation. To go further, you can use the [`getItemUrl`](sources#getitemurl) to add [keyboard accessibility](keyboard-navigation) features. It lets users open items directly from the autocomplete menu.

```jsx title="JSX"
/** @jsx h */
import { autocomplete, getAlgoliaHits } from '@algolia/autocomplete-js';
import algoliasearch from 'algoliasearch';
import { h } from 'preact';

const searchClient = algoliasearch(
'BH4D9OD16A',
'a5c3ccfd361b8bcb9708e679c43ae0e5'
);

function AutocompleteItem({ hit, breadcrumb }) {
// ...
}

autocomplete({
container: '#autocomplete',
placeholder: 'Search documentation',
openOnFocus: true,
getSources({ query }) {
return [
{
getItems() {
// ...
},
templates: {
// ...
},
getItemUrl({ item }) {
return item.url;
},
},
];
},
});
```
Now give it a try: navigate to one of the items using your keyboard and hitting <kbd>Enter</kbd>.

<AutocompleteExample
getSources={({ query }) => {
return [
{
getItems() {
return getAlgoliaHits({
searchClient,
queries: [
{
indexName: 'autocomplete',
query,
params: {
hitsPerPage: 5
}
}
]
});
},
getItemUrl({ item }) {
return item.url;
},
templates: {
item({ item }) {
return (
<AutocompleteDocSearchItem
hit={item}
breadcrumb={Object.values(item.hierarchy)
.filter(Boolean)
.slice(0, -1)}
/>
);
}
},
},
];
}}
/>

## Next steps

This outlines a basic autocomplete implementation. There's a lot more you can do, like [adding multiple sources](creating-multi-source-autocompletes), using [templates for headers, footers](templates#rendering-a-header-and-footer), or when there's [no results](templates#rendering-an-empty-state). To learn about customization options, read the [**Core Concepts**](basic-options) or follow one of the [**Guides**](using-query-suggestions-plugin).

0 comments on commit e75218b

Please sign in to comment.