chore: document the Commit Widget

bosonprotocol · Mar 18, 2024 · 88d4a92 · 88d4a92
1 parent a1b60ac
commit 88d4a92
Show file tree

Hide file tree

Showing 9 changed files with 238 additions and 42 deletions.
diff --git a/README.md b/README.md
@@ -5,6 +5,7 @@
 ## Getting started
 
 - How tos & guides:
+   - [Commit Widget](./docs/commit-widget.md)
    - [Redemption Widget](./docs/redemption-widget.md)
    - Finance Widget
 - [Local development](docs/local-development.md)

diff --git a/docs/assets/commit-widget/1-commit-widget-overall.png b/docs/assets/commit-widget/1-commit-widget-overall.png
diff --git a/docs/assets/commit-widget/2-commit-button.png b/docs/assets/commit-widget/2-commit-button.png
diff --git a/docs/commit-widget.md b/docs/commit-widget.md
@@ -0,0 +1,95 @@
+[![banner](./assets/banner.png)](https://bosonprotocol.io)
+
+< [Boson Protocol Widgets](../README.md)
+
+# The Commit Widget 
+
+## Committing to a Boson Product using the Boson Widget
+
+With the Boson Commit Widget, Sellers can now allow their Customers to Commit to a Boson Product on their own domains.
+
+The Boson Commit Widget allows Sellers to simply embed, via a few lines of code, commit functionality of their products into an existing website.
+
+![Commit Widget overall](./assets/commit-widget/1-commit-widget-overall.png)
+
+To integrate the Boson Commit Widget, all a seller needs to do is:
+
+ 1. Add the following `<script>` entry, either in `<head>` or `<body>` of their website:
+```
+<script async type="text/javascript" src="https://widgets.bosonprotocol.io/scripts/boson-widgets.js"></script>
+```
+
+ 2. The Seller then needs to create a button with the fragment identifier *id="boson-commit"*. When clicked, the commit modal will popup on the Seller's website.
+``` 
+<button type="button" id="boson-commit" data-config-id="production-137-0" data-seller-id="2" data-product-uuid="2540b-1cf7-26e7-ddaf-4de1dcf7ebc">Show Commit</button>
+```
+
+The button shall be parameterized with the following arguments:
+- ```data-config-id```: specifies the Boson Configuration addressed by the widget (here ***production-137-0*** is the production configuration deployed on the Polygon blockchain). See [Boson Environment](./boson-environments.md) to get more details.
+- ```data-seller-id```: specifies the Boson Seller ID that publishes the Product being offered with the plugin
+- ```data-product-uuid```: specified the ProductUUID of the Product being offered with the plugin
+
+When a user will click the "Show Commit" button, the Commit Widget will popup and allow the user to:
+- show details about the specified Product
+- connect their web3 wallet
+- commit to the Product (assuming they have connected their wallet, and have enough funds to commit)
+
+## Using the Boson Commit Button
+
+As a seller you can also choose to use the Boson branded "Commit" Button on your website, if you would like to do this, all you need to do is: 
+
+ 1. Add the below 2 lines of code in HTML `<head>` section:
+```
+ <head>
+    ...
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <link rel="stylesheet" href="https://widgets.bosonprotocol.io/styles.css">
+  </head>
+```
+
+2. Add the below class name to the "boson-commit" button:
+```
+<button type="button" id="boson-commit" class="bosonButton" data-config-id="production-137-0" data-seller-id="2" data-product-uuid="2540b-1cf7-26e7-ddaf-4de1dcf7ebc">Commit</button>
+```
+
+![Commit Widget Button](./assets//commit-widget/2-commit-button.png)
+
+## Integrating the Commit Widget as an iFrame
+
+Instead of using the Commit Button as shown above, the Commit widget can be embedded in any web page using an iFrame HTML tag.
+
+For instance:
+```
+<iframe src="https://widgets.bosonprotocol.io/#/commit?configId=production-137-0&sellerId=2&productUuid=2540b-1cf7-26e7-ddaf-4de1dcf7ebc"></iframe>
+```
+
+In which case the page:
+- does not need to include any specific line (like the ```<script>``` tag for ```boson-widgets.js```)
+- shall manage itself the logic to show and hide the iFrame, and the parameters to pass to its URL.
+- the expected parameters are:
+- ```configId```: specifies the Boson Configuration addressed by the widget (here ***production-137-0*** is the production configuration deployed on the Polygon blockchain). See [Boson Environment](./boson-environments.md) to get more details.
+- ```sellerId```: specifies the Boson Seller ID that publishes the Product being offered with the plugin
+- ```productUuid```: specifies the ProductUUID of the Product being offered with the plugin
+
+## Commit Widget Parameters
+
+The following parameters configures the widget. They must be passed in the widget URL (for instance when building an iFrame).
+For instance:
+```
+<iframe src="https://widgets.bosonprotocol.io/#/commit?configId=production-137-0&sellerId=2&productUuid=2540b-1cf7-26e7-ddaf-4de1dcf7ebc"></iframe>
+```
+
+When using the Commit Button, as shown above, the parameters must be passed as HTML attributes to the Button tag. For instance:
+```
+<button type="button" id="boson-commit" data-config-id="production-137-0" data-seller-id="2" data-product-uuid="2540b-1cf7-26e7-ddaf-4de1dcf7ebc">Commit</button>
+```
+
+| URL parameter | HTML attribute | Required | Default Value | Purpose | Example |
+| ------ | -------- | ------- | ------- | ------- | ------- |
+| configId | data-config-id | yes | none | the Boson Protocol environment the widget is linked to (see [Boson Environments](../boson-environments.md)) | ```"production-137-0"```
+| sellerId | data-seller-id | When offerId is not used | none | specifies the Boson Seller ID that publishes the Product being offered with the plugin. | ```"2"```
+| productUuid | data-product-uuid | When offerId is not used | none | specifies the ProductUUID of the Product being offered with the plugin. | ```"2540b-1cf7-26e7-ddaf-4de1dcf7ebc"```
+| offerId | data-offer-id | When sellerId/productUuid is not used | none | specifies the ID of the Offer being offered with the plugin. Note: an offer ID is the low-level identification of the Boson Offer on-chain, while a Product can match several offers, like several variants (size, color, ...)). | ```"1099"```
+| account | data-account | no | none | the address of the wallet the widget should accept. When specified, the user can't connect any other wallet that the one specified.  This parameter is optional and can be used if you want to prevent the user to use the Commit Widget if they don't connect with the given wallet. | ```"0x023456789abcd0213456789abcd213456789abcd"```
+| lookAndFeel | data-look-and-feel | no | ```"regular"``` | the look and feel for the Widget (```"regular"``` or ```"modal"```). When set to ```"modal"```, allow to define a margin around the widget to be appearing like a modal popup. | ```"modal"```
+| modalMargin | data-modal-margin | no | none | the margin to apply around the widget when lookAndFeel is set to ```"modal"``` | ```"5%"```
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -3,7 +3,7 @@
   "version": "0.1.0",
   "private": true,
   "dependencies": {
-    "@bosonprotocol/react-kit": "^0.29.0-alpha.1",
+    "@bosonprotocol/react-kit": "^0.29.0-alpha.3",
     "@testing-library/jest-dom": "^5.16.5",
     "@testing-library/react": "^13.4.0",
     "@testing-library/user-event": "^13.5.0",

diff --git a/public/example.html b/public/example.html
@@ -19,7 +19,7 @@
   <body>
     <h1>Boson Protocol Widgets</h1>
     <section>
-      <h2>Finance Widget</h2>
+      <h2>Commit Widget</h2>
       <table>
         <thead>
           <tr>
@@ -32,15 +32,33 @@ <h2>Finance Widget</h2>
           <tr>
             <td>SellerId</td>
             <td>
-              <input type="number" min="1" id="input-finance-seller-id" onchange="updateFinanceButton('data-seller-id', this.value)">
+              <input type="number" min="1" id="input-commit-seller-id" onchange="updateCommitButton('data-seller-id', this.value)">
             </td>
             <td>
-              <button onclick="clearFinanceInputs(); setValue('input-finance-seller-id', '26')" >Example</button>
+              <button onclick="setValue('input-commit-seller-id', '26')" >Example</button>
+            </td>
+          </tr>
+          <tr>
+            <td>ProductUuid</td>
+            <td>
+              <input type="string" id="input-commit-product-uuid" onchange="updateCommitButton('data-product-uuid', this.value)">
+            </td>
+            <td>
+              <button onclick="setValue('input-commit-product-uuid', '2256bad-f146-04bd-2a66-6fda84bbe5a')" >Example</button>
+            </td>
+          </tr>
+          <tr>
+            <td>LookAndFeel</td>
+            <td>
+              <input type="string" id="input-commit-look-and-feel" onchange="updateCommitButton('data-look-and-feel', this.value)">
+            </td>
+            <td>
+              <button onclick="setValue('input-commit-look-and-feel', 'regular')" >Example</button>
             </td>
           </tr>
         </tbody>
       </table>
-      <button type="button" id="boson-finance-button" class="bosonButton" disabled>Show Finance</button>
+      <button class="bosonButton" id="boson-commit-button">Show Commit</button>
     </section>
     <section>
       <h2>Redemption Widget</h2>
@@ -225,6 +243,30 @@ <h2>Redemption Widget</h2>
       </table>
       <button class="bosonButton" id="boson-redeem-button">Show Redeem</button>
     </section>
+    <section>
+      <h2>Finance Widget</h2>
+      <table>
+        <thead>
+          <tr>
+            <th>Parameter</th>
+            <th>Value</th>
+            <th></th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td>SellerId</td>
+            <td>
+              <input type="number" min="1" id="input-finance-seller-id" onchange="updateFinanceButton('data-seller-id', this.value)">
+            </td>
+            <td>
+              <button onclick="clearFinanceInputs(); setValue('input-finance-seller-id', '26')" >Example</button>
+            </td>
+          </tr>
+        </tbody>
+      </table>
+      <button type="button" id="boson-finance-button" class="bosonButton" disabled>Show Finance</button>
+    </section>
     <script>
       const searchParams = new URLSearchParams(window.location.search);
       const configId = searchParams.get('configId');
@@ -234,6 +276,9 @@ <h2>Redemption Widget</h2>
       function updateRedeemButton(attribute, value) {
         document.getElementById('boson-redeem-button').setAttribute(attribute, value)
       }
+      function updateCommitButton(attribute, value) {
+        document.getElementById('boson-commit-button').setAttribute(attribute, value)
+      }
       function updateFinanceButton(attribute, value) {
         document.getElementById('boson-finance-button').setAttribute(attribute, value)
         if (value) {