intellij-sdk-code-samples/reference_guide/jcef.md

title
JCEF - Java Chromium Embedded Framework

Warning

JCEF is available since 2020.1 as an experimental feature. We plan to deprecate using JavaFX in 3rd party plugins and switch to JCEF.

JCEF is a Java port of CEF framework for embedding Chromium-based browsers in applications using Swing.

Embedding of the browser component inside the IDE allows amongst others:

• rendering HTML content
• previewing generated HTML (e.g., from Markdown)

Enabling JCEF

Using JCEF requires using a dedicated JetBrains Runtime, please follow these installation instructions on how to obtain and activate it in your IDE. Enable ide.browser.jcef.enabled in Registry dialog (invoke Help | Find Action and type "Registry") and restart the IDE for changes to take effect.

Debugging

When the IDE is running in internal mode, the JCEF process is started in debug mode (with the --inspect flag).

JavaScript debugger in IntelliJ IDEA Ultimate can thus be used to debug JavaScript code running in it. Use the Attach to Node.js/Chrome configurations with the default port 9229.

Alternatively, Chrome's DevTools can be used by invoking internal action Show Web Browser and then choose Tools | Dev Tools | Show Dev Tools in browser frame menu.

API

com.intellij.ui.jcef.JBCefApp

Performs JCEF auto-initialization, manages its lifecycle, and provides JBCefClient instances.

com.intellij.ui.jcef.JBCefClient

Is tied to every browser component explicitly or implicitly. Used for adding handlers to the associated browser. The same instance can be shared among multiple browsers. It is up to the developer to use a shared or per-browser instance, depending on the handlers' logic. If a client was created explicitly, it should be disposed by the developer; otherwise, it is disposed automatically following the associated browser instance disposal.

com.intellij.ui.jcef.JBCefBrowser

Provides the browser UI component:

  JComponent getComponent();

Provides the load methods (callable from non-EDT thread as well):

  void loadURL(String);
  void loadHTML(String);

For executing JS code and callbacks (see below), use the wrapped CefBrowser instance directly:

  getCefBrowser().executeJavaScript(String code, String url, int line);

By default, JBCefBrowser is created with implicit JBCefClient (disposed automatically). It is possible to pass your own JBCefClient (disposed by the developer).

For accessing:

  JBCefClient getJBCefClient();

The simplest way to add a browser component to your UI:

  JPanel myPanel = ...
  myPanel.add(new JBCefBrowser(“https://www.jetbrains.com”).getComponent());

com.intellij.ui.jcef.JBCefJSQuery

Provides JS query callback mechanism.

There’s no direct access to JS DOM from Java (like in JavaFX WebView, see also this issue). Still, JCEF provides an asynchronous way to communicate to JS.

It’s simpler to illustrate it by an example. Say, we want to open a link in an external browser (see it in MarkdownJCEFHtmlPanel):

  // Create a JS query instance
  final JBCefJSQuery myJSQueryOpenInBrowser =
  JBCefJSQuery.create(myJBCefBrowser);
  
  // Add a query handler
  myJSQueryOpenInBrowser.addHandler((link) -> {
            MarkdownAccessor.getSafeOpenerAccessor().openLink(link);
          return null; // can respond back to JS with JBCefJSQuery.Response
        });
  
  // Inject the query callback into JS
  myCefBrowser.executeJavaScript(
  "window.JavaPanelBridge = {" +
            "openInExternalBrowser : function(link) {" +
                  myJSQueryOpenInBrowser.inject("link") +
              "}" +
        "};",
        getCefBrowser().getURL(), 0);
  
  // Dispose the query when necessary
  Disposer.dispose(myJSQueryOpenInBrowser);