@openrelay/web3-element NPM

layout: widget title: "Web3 Element" date: 2018-09-26 08:00:00 -0500 categories: widgets web3_override: true package: web3-element code: html: |

<or-web3>
  This will be displayed on properly configured <strong>web3</strong> clients.

  <div slot="noweb3">
    This will be displayed on clients that do not support <strong>web3</strong>
  </div>

  <div slot="locked">
    This will be displayed when <strong>web3</strong> is present, but no
    user account is available.
  </div>
  <div slot="netunsupported">
    This will be displayed when <strong>web3</strong> is present and
    unlocked, but using an unsupported network.
  </div>
  <!--
    Here we can list the network IDs of supported networks.

    If no elements with slot="net" are listed, all networks are supported
  -->
  <div slot="net">1</div>
  <div slot="net">42</div>
</or-web3>

npm:

"@openrelay/web3-element"

At the top level of any dApp built with OpenRelay's widgets, you'll find the <or-web3> tag. It provides two primary functions:

Managing browser support

In dApps, we need to make sure client browsers support Web3. The <or-web3> tag manages web3 detection, and renders different content depending on the state of Web3. It lets the page author use Shadow DOM Slots to designate content to show. The slots are as follows:

noweb3 — Web3 is not present
locked — The web3 client is locked
netunsupported — The user is connected to an unsupported network
default — All the necessary conditions are met. The default slot is not specified by a tag; any content not in a specifically designated slot tag are considered part of the default slot.

The content of slots can be arbitrary HTML, allowing you to style the content as you see fit, and provide your users with instructions on how to configure their web3 client to work with your dApp.

The <or-web3> tag uses an additional slot, the net slot, to designate which networks are supported by your dApp. If your dApp should work with any Ethereum network, you don't need to designate any net slots. If your dApp is dependent on contracts on specific networks, you should designate the supported network with net slots (you can list as many as you need). If your user's client is connected to a network not listed in your net slots, the content of the netunsupported slot will be displayed. The content of the net slots themselves will never be rendered to a user.

Connecting Child Elements to the Web3 Client

Almost all other widgets in the OpenRelay widget toolkit are dependent on Web3 in one way or another. Managing Web3 clients in each widget can get very tedious, so we've moved that responsibility into the <or-web3> tag.

When an element based on our toolkit is inserted into the page, it emits an event that will be picked up by the first <or-web3> tag in that tags ancestry. That tells the <or-web3> tag that this element needs a web3 object, and will need to be notified if the web3 object changes in the future.

The <or-web3> tag will detect changes in:

Web3 availability
Lock / Unlock status
Selected networks
Selected accounts

When these properties change, the will be communicated to child elements by emitting events.

Additionally, the <or-web3> tag can be use to monitor for new blocks. Rather than having each widget monitor for changes on the blockchain independently, the <or-web3> tag can monitor for new blocks and notify child elements every time a new block is mined, so that child elements need only check their state on block boundaries.

API

Unless you are developing your own widgets, you don't need to worry about the following API. The widgets that ship with OpenRelay's toolkit use these APIs, but you don't need to interact directly with these APIs to use existing widgets.

HTML Attributes

manualEnable — By default, the web3 tag will request authorization from the browser to access the user's web3 accounts as soon as the tag loads. If you want to control the presentation of this dialog to your users, add the manualEnable attribute to your <or-web3> tag. Note that it is then up to your application to call web3.currentProvider.enable().

Events

The <or-web3> tag uses several events to communicate with other DOM elements.

Incoming Events

web3-child — An event emitted when a child element is registered. The event must include an attribute e.detail.element indicating the newly added element. The <or-web3> element will respond with a web3-ready event, and will notify the registered element on future web3 changes.
set-web3 — This event can be triggered in JavaScript to inject a specific web3 object. The event must include an attribute e.detail.web3 indicating the web3 object to be used for this element and its children. This can be used to override the default use of window.web3 and window.ethereum.
subscribe-block — This event is emitted when a child element wishes to subscribe to new block notifications. The event must include an attribute e.detail.element, which is the element that will be notified when new blocks are mined. When the <or-web3> tag detects its first subscribe-block event, it begins checking for new blocks at regular intervals.

Outgoing Events

None of the following events are emitted directly from the <or-web3> tag. Instead, the <or-web3> tag triggers them directly on one or more registered child elements.

web3-ready — Fired when web3 is confirmed to be available. The web3 object is available at e.detail.web3.
web3-network — Fired when the web3 network has changed. The network ID is available at e.detail.network.
web3-account — Fired when the web3 object's primary account has changed. the account address is available at e.detail.account.