OBM 3 Widget Notebook

API quick reference

This notebook focuses on UI building blocks and their interaction flow. Most-used elements:

  1. SubmittableTextBox

  2. TermsButtons

  3. PlaceTaxonomyButtons

  4. ResponseMap

  5. OneBoxCore.run()

For the complete reference, see API Reference.

API methods used in this notebook

class here_search_demo.widgets.input_text.SubmittableText(*args: t.Any, **kwargs: t.Any)

A ipywidgets Text class enhanced with an on_submit() method

on_submit(callback, remove=False)

(Un)Register a callback to handle text submission.

Triggered when the user clicks enter.

Parameters

callback: callable

Will be called with exactly one argument: the Widget instance

remove: bool (optional)

Whether to unregister the callback

trigger_submit()

Programmatically invoke all registered submit callbacks.

This mirrors the behavior when the front-end fires a submit custom event, without reaching into private attributes from outside this subclass.

Return type:

None

class here_search_demo.widgets.input_text.SubmittableTextBox(queue, state, *args, **kwargs)

A ipywidgets HBox made of a SubmittableText and a lens Button

async feed(text, delay=None)

Type text programmatically into the input widget.

Useful for notebook demos/tests that simulate user typing. "\b" characters are interpreted as backspace.

Parameters:

  • text – Text sequence to inject.

  • delay (float | None) – Delay in seconds between characters. Defaults to default_simulation_delay_sec.

submit()

Programmatically trigger a submit.

class here_search_demo.widgets.input_text.TermsButtons(target_text_box, state, values=None, buttons_count=None, index=-1, layout=None)

Suggestion buttons bound to a SubmittableTextBox.

The widget renders one button per value in state.term_suggestions. Clicking a button replaces one token in the target text box and updates SearchState.

Parameters:

  • target_text_box (SubmittableTextBox) – Text widget to update when a button is clicked.

  • state (SearchState) – Shared search state carrying the current term suggestions.

  • values (list[str] | None) – Optional initial suggestions; when provided they are stored in state.term_suggestions before rendering.

  • buttons_count (int | None) – Number of buttons to create when no suggestions are available yet.

  • index (int) – Token index to replace in the target query. -1 replaces the last token, None replaces the whole query text.

  • layout (dict | None) – Optional ipywidgets layout for the button container.

class here_search_demo.widgets.input_text.PlaceTaxonomyButtons(queue, taxonomy, icons, state)

Buttons that emit taxonomy search intents.

Each button maps to one PlaceTaxonomyItem. On click, the selected taxonomy item is stored in state and a SearchIntent(kind="taxonomy", ...) is pushed to queue.

Parameters:

  • queue (Queue) – Queue receiving taxonomy intents.

  • taxonomy (PlaceTaxonomy) – Taxonomy source used to create buttons.

  • icons (Sequence[str]) – Icons/text labels paired with taxonomy items.

  • state (SearchState) – Shared search state updated with the selected taxonomy item.

class here_search_demo.widgets.output_map.ResponseMap(queue=None, state=None, search_center_handler=None, tile_opacity=0.6, **kwargs)

Map widget used to render search responses and selection actions.

The map displays results as GeoJSON markers, optionally adds extra labels (fuel prices / TripAdvisor), and can fit bounds to returned items. It is also interactive: marker clicks push ActionIntent instances to queue so upper layers can retrieve details or trigger detour logic.

Parameters:

  • queue (Queue | None) – Queue used for emitted intents from map interactions.

  • state (SearchState | None) – Shared state containing ranked response items.

  • search_center_handler (Callable[[tuple[float, float]], None]) – Callback invoked when the map center changes.

  • tile_opacity (float) – Base map tile opacity.

  • kwargs – Forwarded to PositionMap.

class here_search_demo.base.OneBoxCore(api=None, queue=None, search_center=None, language=None, results_limit=None, suggestions_limit=None, terms_limit=None, max_transient_keep=None)

Core async controller for one-box search workflows.

OneBoxCore consumes SearchIntent objects from queue, maps them to typed search events, executes API calls, and dispatches responses to dedicated handlers.

Subclasses typically override presentation hooks such as handle_suggestion_list(), handle_result_list(), and handle_result_details() while reusing the routing/transport pipeline.

Parameters:

  • api (API | None) – API adapter. Defaults to here_search_demo.api.API.

  • queue (Queue | None) – Intent queue consumed by run().

  • search_center (Optional[Tuple[float, float]]) – Default (lat, lon) context used by requests.

  • language (str | None) – Preferred language code for requests.

  • results_limit (int | None) – Number of results to expose to UI handlers.

  • suggestions_limit (int | None) – Number of autosuggest items to expose.

  • terms_limit (int | None) – Number of term suggestions to expose.

  • max_transient_keep (int | None) – Maximum queued transient-text intents retained.

handle_result_list(intent, response)
Typically

  • called in OneBoxCore.handle_search_event()

  • associated with OneBoxCore.TextSearchEvent and OneBoxCore.PlaceTaxonomySearchEvent via self.intent_routes

Parameters:

  • intent (SearchIntent) – Response intent

  • response (Response) – Response instance

Return type:

None

Returns:

None

handle_suggestion_list(intent, response)
Typically

  • called in OneBoxCore.handle_search_event()

  • associated with OneBoxCore.PartialTextSearchEvent via self.intent_routes

Parameters:

  • intent (SearchIntent) – Response intent

  • response (Response) – Response instance

Return type:

None

Returns:

None

run(handle_search_events=None)

Start the background consumer task and return self.

Parameters:

handle_search_events (Optional[Callable]) – Optional coroutine factory replacing the default event loop handler.

Returns:

Running app instance.

Return type:

OneBoxCore