Ask

The workflow of a question and its answer. Get the one for the first question from client.workflows.ask.

Each follow-up question is answered by an Ask workflow of its own, chained after the one of its parent question by next and previous. All of them are managed by Asks, available as client.workflows.asks.

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.next`

The workflow of the follow-up question, if it exists.

Type: Ask or undefined

`workflow.parentQuestionId`

The question ID of the parent question. Absent for the first question.

Type: string or undefined

`workflow.previous`

The workflow of the parent question.

Type: Ask or undefined

`workflow.questionId`

The question ID of the current answer, available once the question is accepted by the API.

Type: string or undefined

`workflow.rootQuestionId`

The question ID of the first question in the chain.

Type: string or undefined

`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.autoQuery([options])`

Read the query from the page URL and, if present, run it. Once a query runs, the URL is kept in sync with it.

Parameter	Type	Description
`options`	`Object`	Optional.
`options.param`	`string`	The URL parameter of the query. Default `'q'`. Optional.
`options.sourceParam`	`string`	The URL parameter of the question source. Default `'qs'`. Optional.
`options.setValue`	`boolean`	Put the query into the search box. Default `true`. Optional.
`options.focus`	`boolean`	Focus the search box when there is no query in the URL. Default `true`. Optional.
`options.updateUrl`	`boolean`	Update the URL as new queries run. Default `true`. Optional.

`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.getOrCreateNext()`

Get the workflow of the follow-up question, creating it if it does not exist. Available once this question has a question ID.

Returns Ask or undefined.

`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)`

Ask a question. Starts a new session, replacing the current answer.

If a link function is set by useLink(), navigate to the URL it gives instead.

Parameter	Type	Description
`args`	`Object`
`args.q`	`string`	The question. Optional.
`args.questionId`	`string`	Show the answer of an existing question, instead of asking one. Optional.

`workflow.restart()`

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

Returns this.

`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 page to send a query to. Once set, query() goes to that URL instead of running the query.

Parameter	Type	Description
`fn`	`function` or `false`	Takes the query and returns the URL. Pass `false` to run queries on the current page again.
`options`	`Object`	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.useLink(q => `/search?q=${encodeURIComponent(q)}`);

`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 } } });

IterableApiStub

Asks