README.md
1# Contextual Search Component
2
3The Contextual Search component implements some platform agnostic services that
4mediate between the main CS implementation in the Browser and some other parts
5of the system. These include the JS API service to allow communication from
6the Overlay to CS, and user-interaction aggregation.
7
8## JS API Service
9
10The JS API Service allows JavaScript in the Overlay Panel to call into
11Contextual Search. This is done by providing an entry point at
12chrome.contextualSearch when the Contextual Search Overlay Panel is active.
13
14Enabling this API is somewhat complicated in order to make sure that the API
15only exists for a Renderer created by CS for the Overlay:
16
171. Whenever a Renderer is created, an OverlayJsRenderFrameObserver is created.
18 This class is at the heart of the connection between the Renderer, CS, JS
19 and the JavaScript API.
202. An OverlayJsRenderFrameObserver is created for every renderer to check if
21 it's a CS Overlay Panel. When the renderer starts up it asks Contextual
22 Search if the current URL belongs to its overlay panel, and if it does then
23 the JS API is enabled for that renderer to allow it to accept JS messages
24 from the page.
253. When the OverlayJsRenderFrameObserver gets the response in #2 it creates a
26 ContextualSearchWrapper object that allows injecting JavaScript into the
27 WebFrame.
284. When some JS in a page wants to call into Chrome it simply accesses methods
29 in the chrome.contextualSearch API. If the page is being presented in the
30 Overlay Panel for CS then that object will exist with native method
31 implementations. The renderer forwards the API request to the browser for
32 processing.
33
34The above interaction is used by the Translate onebox to allow showing a
35translation in the caption of the Contextual Search Bar, and to provide control
36of the position of the Overlay.
37
38## User Interaction Aggregation
39
40The CtrAggregator and WeeklyActivityStorage classes are used aggregate user
41actions on a weekly basis for use in machine learning for improved triggering.
42
43