Weekly design meeting #21

We didn't make a meeting minute for meeting #19 and #20 (I forgot how we forgot to do that).

#21 is about the March schema.

We concluded the following. Starting from trivial stuff: renaming


  • <token-card> is renamed to <token>. Previously I thought users might confuse it with the <token> as a root element or the <token> inside <input> and <output>. Seems no one got confused, so we call it <token> to avoid overly complicate things.
  • <view-iconified> is renamed to <item-view>. Previously it was called 'iconified' to show that it's not interactable (like you can't have a button or input box inside an icon) and selectable (like you can Ctrl+click multiple icons). No one interpreted it that way. We gave up and give it a name that might be associated with non-interactable and selectable. Besides, we are considering @tomek's suggestion of implementing icon for each token so "iconified" got in the way. More on that in github.

changing the way view is defined.

Previously a view is a container for HTML blocks. Now it's a container of the following elements:

  • <xhtml:style>
  • <xhtml:script>
  • <xhtml:body>

It might change again as we make them object references so that the developers are not forced to ship them together with TokenScript but rather instead getting them from IPFS etc. I'm sorry.

The use of <xhtml:body> is discouraged because it is not dynamic. It is there mostly for backward compatibility of preëxisting shtml files. @hboon suggested the use of JSX as its replacement, which we will consider or use in the next version of the schema.

As long as javascript is embedded, it needs to be in CDADA. When it becomes object reference all will be easier.

adding ASNX modules

This is the biggest change. You can now define an ASNX module under a contract.

adding event as an origin

Now an attribute can be sourced from an event. An event is filtered by a filter expression.

In our first use-case (ENS), the events filtered is supposed to be reliablly once only, so we didn't have to deal with typical query parameters like sort and unique. We leave that to be added later, since such change doesn't force a schema namespace update, therefore can be done separately.

the design agreed in the meeting but not included in the march schema

  • adding disctinct in attribute-type

A distinct attribute-type is one that defines individual tokens.

Both @JamesB and @hboon opted the use of distinct attribute in place of <origin> tag for token. Such a decision also imply the use of RDN as token identifier instead of fixed TokenID as byte32 (traditional ERC721 tokens are therefore identified as TokenID=0x830234802abcd8034... where it was previously identified as 0x830234802abcd8034..)

However, as this change is non-trivial, we opted to not to implement it until a later stage.

We also talked about a JavaScript API/DOM change for TokenScript views that will among other things, make rendering multiple TokenScript views in a single web view possible:

  1. TokenScript client will now automatically generate a <div> with a unique ID and wrap the TokenScript view with it. This wrapper <div> will have the CSS class .token-card so it can be styled (if desired).

We usually create a <div> with a hardcoded CSS ID — id="root" — in our TokenScript files. This is to be replaced with a CSS class instead. To reduce confusion, we name it .contents (instead of .root) in this snippet:

<div class="contents"></div>
  1. web3.tokens.dataChanged is now called with an additional, 3rd argument tokenCardId, which is the unique ID of the <div> which the TokenScript view is automatically wrapped with.

The dataChanged handler that is often written as such:

web3.tokens.dataChanged = (oldTokens, updatedTokens) => {
    const currentTokenInstance = web3.tokens.data.currentInstance
    const domHtml = new Token(currentTokenInstance).render()
    document.getElementById('contents').innerHTML = domHtml

can be changed to:

web3.tokens.dataChanged = (oldTokens, updatedTokens, tokenCardId) => {
    const currentTokenInstance = updatedTokens.currentInstance
    const domHtml = new Token(currentTokenInstance).render()
    document.getElementById(tokenCardId).getElementsByClassName("contents")[0].innerHTML = domHtml
  1. web3.tokens.data.currentInstance is deprecated and will be removed in the future. One reason to keep it around a bit more is to making debugging easier as it is globally available without waiting and relying on web3.tokens.dataChanged to be triggered correctly (i.e. there might be a runtime error caused by the function). The alternative is to remove it but make web3.tokens.data.all available which should have performance implications.

All these changes are updated in the document.

Some copy and pasted background chat around the discussion of using JSX:

As in when I refer to JSX? Not necessarily. Weiwu would like to consider supporting it [React] directly by offering a specific version (or a list to choose from) and building support by bundling the React framework libraries with TokenScript clients so TokenScript files are not bloated by the [React] library.

An alternative is provide a template language, so I suggested looking at JSX (just that “template” language).

React and generally most full blown libraries like it will bring very bad performance especially to the view-iconified cards which has more than 1 web view in a screen and because users are accustomed to good performance in table views.