Skip to content

Commit

Permalink
feat: Updated TokenScript documentation WIP
Browse files Browse the repository at this point in the history
  • Loading branch information
micwallace committed Sep 1, 2024
1 parent c375d4c commit 7a85a92
Show file tree
Hide file tree
Showing 2 changed files with 111 additions and 1 deletion.
1 change: 1 addition & 0 deletions pages/framework/tokenscript-syntax/attributes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@ Here is an example of how you would find the ENS name for a specific ENS token:
```

Note: We plan to support more attribute sources in the near future, including fetching data from HTTP APIs.
In the meantime you can always fetch these values via Javascript and make them available by the `tokenscript.action.setProps()` method of the Card SDK.

### Attribute placement

Expand Down
111 changes: 110 additions & 1 deletion pages/framework/tokenscript-syntax/cards.mdx
Original file line number Diff line number Diff line change
@@ -1 +1,110 @@
# Cards
# Cards

TokenScript cards are used to define UIs for particular token collection/s.
Your HTML, CSS, JS is embedded within `ts:cards` during the build process.
There are a few different types of cards, and these apply to different scenarios.

Each token can have an unlimited amount of cards associated with it. They can be used to display token information,
perform single actions or be an entrypoint to a rich application that allows the user to perform many action from the same card.

Cards can also be disabled based on attribute conditions using the `ts:selection` element that is detailed here (TODO).

## Cards Example

```xml
<ts:cards>
<ts:viewContent name="common" xmlns="http://www.w3.org/1999/xhtml">
<ts:include type="html" src="./dist/index.html"/>
<ts:include type="css" src="./src/styles.css"/>
</ts:viewContent>

<ts:card type="token" name="Info" origins="ReallyCoolToken">
<ts:label>
<ts:string xml:lang="en">Cat Bio</ts:string>
</ts:label>
<ts:view xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" urlFragment="info">
<ts:viewContent name="common"/>
</ts:view>
</ts:card>

<ts:card type="action" name="levelUp" origins="ReallyCoolToken" exclude="cantLevelUp">
<ts:label>
<ts:string xml:lang="en">Level Up!</ts:string>
</ts:label>
<ts:transaction>
<ethereum:transaction as="uint" contract="ReallyCoolToken" function="levelUp">
<ts:data>
<ts:uint256 ref="tokenId"/>
</ts:data>
</ethereum:transaction>
</ts:transaction>
<ts:view xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" urlFragment="levelUp">
<ts:viewContent name="common"/>
</ts:view>
</ts:card>
</ts:cards>
```

## ts:viewContent

The `ts:viewContent` tag is used to define common web content that can be used across different cards.
This helps to prevent duplication of code used within multiple cards (such as a common library) and allows the ability to
use an SPA (single page application) for all of your token cards.

The same `ts:viewContent` tag can then be placed within `ts:view` to reference the view content using the name attribute.

## ts:include

The `ts:include` tag is used to reference external HTML, CSS & JS files that are to be inlined during the build process.
When building a TokenScript project, the CLI will look for these tags and replace them with the content of the corresponding file.
This tag can be placed in both `ts:view` & `ts:viewCotent` elements.

The `ts:view` & `ts:viewContent` elements can also include any valid HTML tags, however it is recommended to use `ts:include` and let the TokenScript CLI take care of this.

## ts:card

Each `ts:card` element defines a separate card. These are often displayed to the user as a button.

### Card Types

The card type is defined by using the `type` attribute.

- **token:** This is the primary card type and is usually used to display information about the corresponding token, but can also be used to execute transactions.
- **action:** These cards are intended to perform specific token-related actions.
By default, they display the view along with a button at the bottom to trigger the defined transaction or another action
- **activity:** This card type is analogous with an action card.
- **onboarding:** Like all other types, this card is not associated with any token and can be access by users that don't have a token yet.
The most common use-case for this card is allowing the user to mint a token to gain access to other cards.

### name

The `name` attribute is a unique name for your card. This value is used for deep-links that open a specific card.
i.e. https://viewer.tokenscript.org/?chain=137&contract=0xB48f53010Acbc0E24D3D12D892E2215879e6fD13#card=Play&tokenId=715

### origin

The `origin` attribute defines the token origins that this card should be shown for.
It can contain multiple space-separated values and must match the name of the contracts defined in the `ts:origins` element.
i.e. `origins="ReallyCoolToken MyOtherTokenCollection"`

### exclude

The `exclude` attribute references a `ts:selection` element. When the selection criteria is a match for this token, the card is disabled.

## ts:label

This label is used as the button text for this card and uses the same syntax as other `ts:label` tags used throughout the tokenscript.xml

## ts:view

The `ts:view` element defines the web content for this card and also has several attributes that control the UI for this card

### urlFragment

The `urlFragment`

### uiButton

### fullScreen


0 comments on commit 7a85a92

Please sign in to comment.