openHitListByIds()

Open a mixed hit list with the given objects. One of the seven portable facade methods of the Dashlet handle — see call for the string-based surface, which shares the same dispatch core.

1. Signature

openHitListByIds(options: OpenHitListByIdsOptions): Promise<void>;

2. Parameters

Name Type Description

objects

Array of { objectId, objectTypeId }

The objects to display in the hit list.

inNewTab

boolean (optional)

Open in a new tab (webclient only). true makes the call awaited (correlated post); false or omitted makes it fire-and-forget (see below).

title

string (optional)

Hit-list title. The rich client requires a non-empty title — an empty/omitted title is substituted with the fixed default 'Result list'.

description

string (optional)

Hit-list subtitle (webclient only; the bridge has no equivalent).

executeSingleHitAction

boolean (optional)

Execute the single hit’s default action (webclient only; the bridge has no equivalent).

3. Per-environment behavior

Environment Behavior

webclient

The params slot is an object { objects, inNewTab, title, description, executeSingleHitAction } (unlike the plain arrays of the other methods). Fire-and-forget rule: inNewTab !== true posts WITHOUT msgId and resolves immediately — the view change can destroy the dashlet iframe before a reply arrives, so a correlated post would time out pointlessly. Client-side errors on fire-and-forget posts are not reported (documented host quirk). inNewTab === true is correlated and awaited.

rich client

osjxOpenResultList(<single JSON string>) — exactly one argument, a JSON string of shape { title, hits: [{ id, type }] } with string id/type forms. An empty/omitted title is substituted with the fixed default 'Result list' (the bridge requires non-empty). inNewTab, description, and executeSingleHitAction have no bridge equivalent and are not sent. Resolves undefined.

standalone (or still detecting without a wire)

No host reply path exists — the call rejects (bounded) with the TimeoutError so callers can render a fallback instead of hanging.

4. Examples

await dashlet.openHitListByIds({
    objects: [{ objectId: '1024', objectTypeId: 262145 }],
    inNewTab: true,
    title: 'Open documents',
});

5. Errors

  • TypeError — a malformed options object: the options must be a plain object containing an objects array (the normalization rejects any other shape descriptively).

  • Error('dashlet destroyed') — the dashlet was destroyed before the call.

  • TimeoutError — bounded no-reply in standalone, or a correlated (inNewTab === true) webclient post whose host never answered within timeoutMs. Fire-and-forget posts never time out (they resolve immediately).

  • The host’s { error } payload — when the host reports a failure on the webclient method call.