Explore

The workflow of an explore unit, which shows related questions, and a search box to ask a question, on a page other than the answer page. Get one from client.workflows.explores, or the default one from client.workflows.explore.

Questions go to the answer page, by the URL given by the link function set by useLink(). Clicking a related question emits a select event.

const workflow = client.workflows.explore;
workflow.useLink(q => `/answer?q=${encodeURIComponent(q)}`);
workflow.start();

Instance properties

`workflow.autocomplete`

The autocomplete workflow, which suggests completions as the user types in the search box.

Type: Autocomplete

`workflow.destroyed`

Whether the workflow is destroyed.

Type: boolean

`workflow.id`

The unit ID.

Type: string

`workflow.productId`

Type: string

`workflow.states`

The current states of the workflow, by field name, such as data. For debugging.

Type: Object

`workflow.status`

The status of the data: initial, loading, ready, or erroneous.

Type: string or undefined

`workflow.trackers`

The trackers of the workflow, which track impressions, viewables, and clicks of the rendered items.

Type: Object

`workflow.views`

The views of the workflow: the elements bound to it, by role.

Type: Object

Instance methods

`workflow.clearApi()`

Remove the API options set by useApi().

Returns this.

`workflow.clearDataProcessor()`

Remove the functions added by useDataProcessor().

Returns this.

`workflow.clearInteractions()`

Remove the interaction options set by useInteractions().

Returns this.

`workflow.clearLayouts()`

Remove the layout options set by useLayouts().

Returns this.

`workflow.clearTrackers()`

Remove the tracker options set by useTrackers().

Returns this.

`workflow.notifyViewUpdate(role, [state])`

Tell the workflow that a view of a role is rendered, when the view is rendered by your own code. Lifecycle events are emitted off the view of the main role.

Parameter	Type	Description
`role`	`string`	The role.
`state`	`Object`	The view state. Status defaults to `ready`. Optional.

Returns this.

`workflow.on(name, callback)`

Listen to an event.

Parameter	Type	Description
`name`	`string`	The event name, or `'*'` for all events.
`callback`	`function`	Called with `(data, meta)` on every event, where `meta` carries the event `name` and the timestamp `ts`.

Returns function: A function to remove the listener.

`workflow.once(name)`

Wait for the next occurrence of an event.

Parameter	Type	Description
`name`	`string`	The event name.

Returns Promise<{data: *, meta: Object}>: The event, with its data and meta.

`workflow.query(args)`

Go to the answer page of a question, by the URL given by the link function.

Parameter	Type	Description
`args`	`Object`
`args.q`	`string`	The question.

`workflow.restart()`

Start a new session, discarding the data of the current one, along with any API call in progress.

Returns this.

`workflow.start([options])`

Start the workflow, loading the related questions.

Parameter	Type	Description
`options`	`Object`	Optional.
`options.relatedQuestions`	`boolean`	Set to `false` to skip loading related questions. Default `true`. Optional.

Returns this.

Throws Error: If useLink() is not called yet.

`workflow.updateCompletions(data)`

Show completions in the search box, provided by your own code.

Parameter	Type	Description
`data`	`Object`	The completions data.

Returns this.

`workflow.updateData(data)`

Update the workflow with data from your own source, instead of calling the API. The data must carry the current session, or it is ignored.

Parameter	Type	Description
`data`	`Object`
`data.session`	`Object`	The current session, `workflow.session`.
`data.value`	`*`	The data value, in the shape of the API response. Optional.
`data.error`	`Object`	The error, if the data failed to load. Optional.

Returns this.

Throws Error: If data or its session is missing.

workflow.updateData({ session: workflow.session, value: response });

`workflow.useApi([name], [payload])`

Set the API to call, and extra payload to send with each request.

Parameter	Type	Description
`name`	`string` or `Object` or `false`	The API name, such as `'questions'`, or with its group, such as `'ask/questions'`. Pass the payload object alone to keep the API, or `false` to stop calling the API, so you can provide data by `updateData()` instead. Optional.
`payload`	`Object`	Extra payload, merged into the request payload. Optional.

Returns this.

workflow.useApi("ask/questions", { source_fl: ["title", "url"] });

`workflow.useDataProcessor(fns)`

Add functions to process the data before it is rendered. They run in the order they are added.

Parameter	Type	Description
`fns`	`function` or `function()[]`	Functions taking `(data, oldData)` and returning the processed data.

Returns this.

`workflow.useInteractions(options)`

Set how interactions are sent.

Parameter	Type	Description
`options`	`Object` or `false`	Pass `false` to stop sending interactions.
`options.preprocess`	`function` or `function()[]`	Functions taking the interaction payload and returning the modified one, run before it is sent. Optional.
`options.handle`	`function`	A function taking the interaction payload, to send it yourself instead. Optional.

Returns this.

`workflow.useLayouts(options)`

Set the layouts, by role.

Parameter	Type	Description
`options`	`Object` or `false`	The layout of each role, as a layout name, layout options, or `[name, options]`. Pass `false` to stop rendering.

Returns this.

workflow.useLayouts({
  query: { placeholder: "Ask a question" },
  products: "list",
});

`workflow.useLink(fn, [options])`

Set the function giving the URL of the answer page for a question. Required before start().

Parameter	Type	Description
`fn`	`function`	Takes the question and returns the URL.
`options`	`Object`	Optional.
`options.showUrl`	`boolean`	Show the URLs on the related question links. Optional.
`options.open`	`boolean`	Set to `false` to navigate in the current window, instead of opening a new one. Optional.
`options.target`	`string`	The target of the new window. Default `'_blank'`. Optional.
`options.windowFeatures`	`string`	The features of the new window. Default `'noopener'`. Optional.

Returns this.

`workflow.useTrackers(options)`

Set the trackers, by role.

Parameter	Type	Description
`options`	`Object` or `boolean`	`true` or `false` to turn all trackers on or off, or the options of each role: `active`, and the options of each event type, `impression`, `viewable` (`area` and `duration`), and `click` (`lenient`).

Returns this.

workflow.useTrackers({ products: { viewable: { duration: 2000 } } });

HybridSearch

Explores