Embedded Browser (JCEF)

Browser

JCEF browser is represented by JBCefBrowser class. It is responsible for loading and rendering requested documents in the actual Chromium-based browser.

JCEF browsers can be created either by using the JBCefBrowser class' constructors, or via JBCefBrowserBuilder. Use constructors in the cases when a browser with the default client and default options is enough. The builder approach allows using custom clients and configuring other options.

Browser Client

Browser client provides an interface for setting up handlers related to various browser events, e.g.:

• HTML document loaded

• console message printed

• browser gained focus

Handlers allow reacting to these events in plugin code and change browser's behavior. Each browser is tied to a single client and a single client can be shared with multiple browser instances.

Browser client is represented by JBCefClient, which is a wrapper for JCEF's CefClient. JBCefClient allows registering multiple handlers of the same type, which is not possible with CefClient. To access the underlying CefClient and its API, call JBCefClient.getCefClient().

Event Handlers

JCEF API provides various event handler interfaces that allows handling a wide set of events emitted by the browser. Example handlers:

• CefLoadHandler - handles browser loading events.
  Example: Implement CefLoadHandler.onLoadEnd() to execute scripts after document is loaded.

• CefDisplayHandler - handles events related to browser display state.
  Example: Implement CefDisplayHandler.onAddressChange() to load project files in the browser when a local file link is clicked, or opening an external browser if an external link is clicked.

• CefContextMenuHandler - handles context menu events.
  Example: Implement CefContextMenuHandler.onBeforeContextMenu() to change the items of the browser context menu.

• CefDownloadHandler - file download events.
  Example: Implement CefDownloadHandler.onBeforeDownload() to enable downloading files in the embedded browser.

See org.cef.handler package for all available handlers.

Handlers should be registered with JBCefClient.getCefClient().add*Handler() methods.

Executing JavaScript

JCEF API allows executing JavaScript code in the embedded browser from the plugin code. JavaScript can be used for manipulating DOM, creating functions required in implemented features, injecting styles, etc.

In the simplest case, JavaScript code can be executed by using JBCefBrowser.getCefBrowser().executeJavaScript(), e.g.:

The above snippet will be executed in the embedded browser and will display alert box with the "Hello World!" message. The url and lineNumber parameters are used in the error report in the browser, if the script throws an error. Their purpose is to help debugging in case of errors, and they are not crucial for the script execution. It is common to pass browser.getCefBrowser().getUrl() or null/empty string, and 0 as these parameters.

Executing Plugin Code From JavaScript

JCEF doesn't provide direct access to DOM from the plugin code (it may change in the future) and asynchronous communication with JavaScript is achieved with the callback mechanism. It allows executing plugin code from the embedded browser via JavaScript, e.g., when a button or link is clicked, a shortcut is pressed, a JavaScript function is called, etc.

JavaScript query callback is represented by JBCefJSQuery. It is an object bound to a specific browser, and it holds a set of handlers that implement the required plugin behavior.

Consider a case, which requires opening local files links in the editor and external links in an external browser. Such a requirement could be implemented as follows (each step is explained under the code snippet):

1. Create JBCefQuery instance. Make sure that the passed browser instance is of type JBCefBrowserBase (casting may be needed).

2. Add a handler implementing a plugin code to be executed. Example implementation opens a link in the editor or an external browser depending on whether the link is local or external.

3. Handlers can optionally return JBCefJSQuery.Response object, which holds information about success or error occurred on the plugin code side. It can be handled in the browser if needed.

4. Execute JavaScript, which creates a custom openLink function.

5. Inject JavaScript code responsible for invoking plugin code implemented in step 2. The handler added to openLinkQuery will be invoked on each openLink function call.

   Note the "link" parameter of the JBCefJSQuery.inject() method. It is the name of the openLink function's link parameter. This value is injected to the query function call, and can be any value that is required by handler, e.g., "myJsObject.prop", "'JavaScript string'", etc.

6. Execute JavaScript, which registers a click event listener in the browser. Whenever an a element is clicked in the browser, the listener will invoke the openLink function defined in step 4 with the href value of the clicked link.

Loading Resources From Plugin Distribution

In cases when a plugin feature implements a web-based UI, the plugin may provide HTML, CSS, and JavaScript files in its distribution or build them on the fly depending on some configuration. Such resources cannot be easily accessed by the browser. They can be made accessible by implementing proper request handlers, which make them available to the browser at predefined URLs.

This approach requires implementing CefRequestHandler, and CefResourceRequestHandler, which map resource paths to resource providers.

Serving such resources is implemented by the Image Viewer component responsible for displaying SVG files in IntelliJ Platform-based IDEs. See JCefImageViewer and related classes for the implementation details.

Scrollbars Look and Feel

Default browser scrollbars may be insufficient, e.g. when they stand out of the IDE scrollbars look, or specific look and behavior is required.

In JCEF browsers, scrollbars look and feel can be customized by CSS and JavaScript. IntelliJ Platform provides JBCefScrollbarsHelper that allows to customize scrollbars in two ways:

1. Using JBCefScrollbarsHelper.getOverlayScrollbarStyle(), which provides the styles adapted to the IDE scrollbars.

2. Using OverlayScrollbars library adapted to the IDE look and feel. For the details, see getOverlayScrollbarsSourceCSS(), getOverlayScrollbarsSourceJS(), and buildScrollbarsStyle() Javadocs. It should be used when transparent scrollbars or other advanced options are required.

Disposing Resources

JBCefBrowser, JBCefClient, and JBCefJSQuery classes implement JBCefDisposable, which extends Disposable. It means that these classes should clean up their resources according to the rules described on the Disposer and Disposable page.

For example, a custom JBCefClient with registered handlers should remove them in the dispose() method implementation.

Accessing DevTools Programmatically

To access the Chrome DevTools in the plugin code, use the following API:

In order to open DevTools in a separate window, call JBCefBrowser.openDevtools().