Getting Started

Install

yarn add @formidable-webview/webshell

How does it work?

@formidable-webview/webshell exports makeWebshell, a HOC which creates augmented WebView components. This component (from now on, we'll call that a shell component), is very similar to the underlying WebView it is decorating, but will have additional props and eventually, behave slightly differently, depending on the injected Web features passed to makeWebshell. Moreover, these features form an abstraction layer over WebView's messaging system, thus the “shell” in webshell. This layer makes it very easy to implement bidirectional communication flows between Web and Native.

What is a (Web) Feature?

Definition

In the context of webshell, a Web feature is like a plugin. It encapsulates behaviors injectable into WebView. More precisely, a feature can do the following things:

  • Alter the content of the DOM;
  • Inject behaviors through scripts in the Web environment;
  • Handle messages sent from Web environment with shell handler props.
  • Handle messages sent from native code with web handler functions.

Features with shell handlers will augment the WebView with message handler props, for example onDOMLinkPress. Here are examples of handler features you can instantiate in a shell:

Learn More about Web Features

What is a Shell?

This library exposes one landmark function, makeWebshell, a HOC which augments a WebView passed as first argument with features passed as remaining arguments.

~ API Reference ~
makeWebshell

Features are classes customizable during instantiation, where you can pass an object of options to their constructor. Sometimes, a feature options object might not have required fields, and you can skip the constructor argument if you are OK with the defaults.

tip

If you are developing functional components, you can use the hook variant instead: useWebshell

In the bellow snippet, we are creating a component which augments WebView with the two features previously mentioned, but of course any number of features could be instantiated!

const Webshell = makeWebshell(
WebView,
new HandleLinkPressFeature({ preventDefault: true }),
new HandleHTMLDimensionsFeature({ forceImplementation: 'mutation' })
);
note

We will use the word shell as an alias to instances of WebshellComponent produced by makeWebshell function.

The injected features will add two props to the shell, which already supports all WebView props:

  • onDOMLinkPress
  • onDOMHTMLDimensions

Now it's time to try out this code in a complete example.

Minimal Example

caution

This example is shown for didactic purposes. If you need an autoheight WebView , read the guide dedicated to useAutoheight hook which is considerably more robust.

The below example will benefit from two features to implement the following behaviors:

NaiveAutoheightWebView.tsx

As you can see, each feature has added one event handler prop to the shell, onDOMLinkPress and onDOMHTMLDimensions. When the DOM is loaded, the two feature scripts are executed and register handlers to communicate with the shell:

  • onDOMLinkPress is invoked when the user clicks on anchors. The above implementation opens links to system browser thanks to React Native Linking API.
  • onDOMHTMLDimensions is invoked when the page content size changes. The above implementation stores this size in a local state and injects it to the shell style prop. We have just created a naive Autoheight WebView!
caution

This example is shown for didactic purposes. If you need an autoheight WebView , read the guide dedicated to useAutoheight hook which is considerably more robust.

Edit this page
Last updated on by Jules Sam. Randolph