feat: Updated TokenScript documentation WIP

SmartTokenLabs · Sep 3, 2024 · c194ce4 · c194ce4
1 parent 7a85a92
commit c194ce4
Show file tree

Hide file tree

Showing 3 changed files with 111 additions and 3 deletions.
diff --git a/pages/framework/tokenscript-syntax/attributes.mdx b/pages/framework/tokenscript-syntax/attributes.mdx
@@ -86,4 +86,19 @@ It's important to consider how top-level attributes may impact performance when
 - contractAddress (in the context of a token card)
 - tokenId (in the context of a non-fungible token)
 - ownerAddress (the owner of the current token, usually the currently connected wallet address).
-- chainId (The chain for the current token)
+- chainId (The chain for the current token)
+
+## Complex return types
+
+Smart contracts often return complex data types such as multiple return values, arrays & structs (often referred to as tuples).
+TokenScript attributes can fetch and decode this complex data, as long as the ABI fragment for that method is available in the referenced `ts:contract`.
+
+Simply change the `as` parameter of `ts:call` to `abi`:
+
+```xml
+<ethereum:call function="getComplexInfo" contract="ReallyCoolToken" as="abi">
+	<ts:data>
+		<ts:uint256 ref="tokenId"/>
+	</ts:data>
+</ethereum:call>
+```
diff --git a/pages/framework/tokenscript-syntax/cards.mdx b/pages/framework/tokenscript-syntax/cards.mdx
@@ -101,10 +101,19 @@ The `ts:view` element defines the web content for this card and also has several
 
 ### urlFragment
 
-The `urlFragment`
+The `urlFragment` fragment attribute is used to support routing within TokenScript projects built as an SPA.
+When the card is loaded this value is added onto the document.location.hash.
 
 ### uiButton
 
+For simple actions, TokenScript viewer UI provides a button at the bottom of the card that can be used to trigger the
+default transaction or invoke the window.onConfirm function defined by the script.
+
+This button is shown by default on action cards and disabled by default on all other cards. The "uiButton" attribute can be used to override the default behavior.
+
 ### fullScreen
 
+By, default cards are shown as a popup modal and should use a responsive design to ensure a good user experience on mobile devices.
+The default max size for the popover modal in TokenScript viewer is 500px wide & 700px high.
 
+If your card should be full screen, simply set `fullScreen="true"`.
diff --git a/pages/framework/tokenscript-syntax/transactions.mdx b/pages/framework/tokenscript-syntax/transactions.mdx
@@ -1 +1,85 @@
-# Transactions
+# Transactions
+
+One powerful feature of the TokenScript framework is the concept of declarative transactions.
+They provide an easy way to invoke ethereum transactions without writing lots of Javascript.
+In fact, it's possible to wire up simple transactions without a single line of imperative code!
+This is because transactions take advantages of attribute values which they can reference for use in the smart contract's method parameters.
+This is also true for user-input attributes, which can be automatically collected by the engine & card SDK before invoking a transaction.
+
+## A simple action card example
+
+This card implements the erc-721 transfer function and does so without any Javascript:
+
+```xml
+<ts:card type="action" name="Transfer" origins="ReallyCoolToken">
+	<ts:label>
+		<ts:string xml:lang="en">Transfer</ts:string>
+	</ts:label>
+	<ts:attribute name="toAddress">
+		<ts:type>
+			<ts:syntax>1.3.6.1.4.1.1466.115.121.1.27</ts:syntax>
+		</ts:type>
+		<ts:label>
+			<ts:string xml:lang="en">To Address</ts:string>
+		</ts:label>
+		<ts:origins>
+			<ts:user-entry as="address"/>
+		</ts:origins>
+	</ts:attribute>
+	<ts:transaction>
+		<ethereum:transaction contract="ReallyCoolToken" function="safeTransferFrom" as="uint">
+			<ts:data>
+				<ts:address ref="ownerAddress"/>
+				<ts:address local-ref="toAddress"/>
+				<ts:uint256 ref="tokenId"/>
+			</ts:data>
+		</ethereum:transaction>
+	</ts:transaction>
+	<ts:view xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" urlFragment="transfer">
+		<ts:viewContent name="common"/>
+	</ts:view>
+</ts:card>
+```
+
+The syntax for transactions is very similar to attributes that use `ethereum:call`.
+Note: Attributes defined within the card (either in XML or via Card SDK `setProps`) should use `local-ref` rather than `ref` to reference attributes.
+
+Since we have defined our user-input attribute `toAddress`, we only need to supply an input field in the view with the same ID:
+
+```html
+<div style="margin-bottom: 18px;background-color: #F5F5F5;border-radius: 20px;font-weight: 300;padding: 18px;">
+	<p style="margin: 7px 0;font-weight: 400;font-size: 14px;">
+	  Account Address
+	</p>
+	<input
+	  minlength="42"
+	  maxlength="42"
+	  placeholder="To Address"
+	  id="toAddress"
+	  style="padding: 12px 14px; width: 100%; border-radius: 4px; border: 1px solid #B6B6BF; margin: 5px 0;"
+	  type="text"
+	/>
+  </div>
+```
+
+The engine will ask the card SDK to collect the input value before invoking the transaction.
+The other parameters (ownerAddress & tokenId) are intrinsic attributes that are known by the engine, but can also be user-define attributes.
+
+## Setting inputs programmatically
+
+Sometimes using direct user input may not be possible, such as when the input requires some
+processing to get the final value, or when the value is calculated based on some off-chain logic.
+
+The Card SDK's `tokenscript.action.setProps()` method can be used to programmatically set parameter values.
+You do not have to define `ts:user-entry` attributes when using `setProps`.
+
+Note: When using `setProps`, make sure you don't have any HTML input elements with the same ID as the keys you set may be overwritten.
+Alternatively you can define `data-ts-prop="false"` on the input element to disable the automatic collection of input fields.
+
+## Invoking transactions
+
+### UI Button
+
+### Card SDK
+
+