3box-comments-react
节点包是一个嵌入式 React 组件,它为 Web3 开发人员的以太坊应用程序提供现成的评论系统。 只需一行代码,即可轻松将丰富、去中心化的社交话语添加到您的 dApp。 3Box Comments 插件是使用 3Box 基础架构构建的,并处理创建评论线程的所有逻辑。 阅读 docs.3box.io 上的文档。
New Social Features:
回复 - 内联回复评论(限于两级回复),已删除评论的嵌套回复保持嵌套回复
表情符号反应 - 使用内联选择器中的表情符号对每条评论做出反应
投票 - 对任何评论投赞成票或反对票
注意:这是一个破坏性的变化——这将破坏任何以前使用的评论,要创建一个新的评论,只需更新同一空间中的 threadName
How it Works
Architecture
Comments 插件是使用 Open Threads 的标准实现构建的在 3Box Threads API 中定义并通过 3Box.js SDK
。 Comments 插件还包括用于输入和显示用户评论的 UI、用于获取用户配置文件的逻辑和分页。 该组件可配置为各种身份验证模式,并且可以处理 Web3/3Box 登录和登录。 注销状态。
Authentication
无需身份验证,用户可以阅读评论线程中的消息。 但是,需要身份验证才能执行更多交互功能。 用户通过身份验证后,用户可以发表评论、删除自己的评论,以及实时接收其他用户的评论。 注意:如果你没有登录并且组件没有传递你的以太坊地址,组件无法知道哪个评论属于你以便删除。 在这种情况下,单击输入 UI 正下方的登录按钮。
Getting Started
- Install the component
- Choose your authentication pattern
- Configure application settings
- Usage
1. Install the component
npm i -S 3box-comments-react
2. Choose your authentication pattern
根据您的 dApp 何时以及如何处理 web3 和 3Box 的身份验证,您将需要为组件提供一组不同的道具。 无论上下文如何,组件在安装之前都必须传递给以太坊提供者或用户的盒子对象。 以下 AC 中讨论了三种可接受的身份验证模式及其各自的道具:
A) Dapp 处理 web3 和 3Box 登录,并且它们在组件安装之前运行。 (推荐)
Dapp 集成了3Box.js SDK
和3box-comments-react
组件。 在这种情况下,应该将通过 3Box.js 从 Box.openBox(ethAddr)
返回的 box
实例传递给注释中的 box
属性成分。 用户当前的以太坊地址应传递给 currentUserAddr
属性,以确定对每个评论的 deletePost
访问权限。
B) Dapp 处理 web3 和 3Box 登录,但它们在组件安装之前没有运行。 (推荐)
Dapp 集成了3Box.js SDK
和3box-comments-react
组件。 在这种情况下,dapp 中实现的登录逻辑应该作为 loginFunction
prop 传递给 Comments 组件,该组件在用户尝试发表评论时运行。 用户当前的以太坊地址应传递给 currentUserAddr
属性,以确定对每个评论的 deletePost
访问权限。
C) Dapp没有web3和3Box登录逻辑。
Dapp只集成了3box-comments-react
组件,没有集成3Box.js SDK
. 所有 web3 和 3Box 登录逻辑都将在 Comments 组件中处理,尽管它需要将来自 dapp 首选 web3 提供程序的 ethereum
对象传递到组件中的 ethereum
属性.
Best practice
为获得最佳用户体验,我们建议实施以下身份验证模式之一:A; B; 或 B 与 A。
这些模式中的每一个都允许您的应用程序使 box
对象在全局应用程序状态下可用,无论用户在哪个页面上, Comments 组件的所有实例都可以使用它。 这种全局模式消除了用户在他们希望评论的每个页面上进行身份验证的需要,这在 C 中就是这种情况。
首先,为您的应用程序的 3Box 空间选择一个名称。
尽管您是自由的要为您的应用程序空间选择您喜欢的名称,我们建议使用您的应用程序的名称。 如果您的应用程序已经有一个 3Box 空间,欢迎您使用同一个空间进行评论。
接下来,为您的应用程序的线程选择一个命名约定。
评论线程需要一个名称,我们建议您的应用程序根据一个简单的规则创建threadNames
。 我们通常喜欢使用自然标识符,例如社区名称、页面 URL、令牌 ID 或其他类似方式。
然后,为您的应用程序创建一个管理员 3Box 帐户。
每个线程都需要有一个管理员 (adminEthAddr
),该管理员有权管理该线程。 我们建议您为您的应用程序创建一个管理员以太坊帐户,以便您可以执行这些操作。 虽然从技术上讲,您可以使用任何以太坊地址作为管理员帐户,但我们建议为该地址创建一个 3Box 配置文件,这样如果您需要在线程,其他人会知道并信任您作为管理员。
最后,初始化您的应用程序的空间。
在您的 dapp 中部署线程之前,您的应用程序的管理员帐户(adminEthAddr
在上一步中创建)必须首先打开空间(spaceName
) 将用于存储应用程序的线程。 此步骤必须完成,您的评论线程才能被其他人使用。 这个过程可能会在你的 dapp 上下文之外完成,可能是在测试环境中。
只需通过运行(通过3Box.js SDK
)打开一个空间:
const box = await Box.openBox(adminEthAddr, ethereum);
const space = await box.openSpace(spaceName, spaceOpts);
签署web3提示以完成空间初始化过程。
4. Usage
Example
import ThreeBoxComments from '3box-comments-react';
const MyComponent = ({ handleLogin, box, ethereum, myAddress, currentUser3BoxProfile, adminEthAddr }) => (
<ThreeBoxComments
// required
spaceName="mySpaceName"
threadName="myThreadName"
adminEthAddr={adminEthAddr}
ethereum={ethereum}
// Required props for context A) & B)
box={box}
currentUserAddr={myAddress}
// Required prop for context B)
loginFunction={handleLogin}
// optional
members={false}
showCommentCount={10}
threadOpts={{}}
useHovers={false}
currentUser3BoxProfile={currentUser3BoxProfile}
userProfileURL={address => `https://mywebsite.com/user/${address}`}
/>
);
Prop Types
Property |
Type |
Default |
Required Case |
Description |
spaceName |
String |
|
Always |
Likely your dApp name and / or comment category. A single spaceName with different threadName s is common practice when building a dApp with multiple Comment threads. |
threadName |
String |
|
Always |
A name specific to this Comments thread. |
adminEthAddr |
String (Ethereum Address) |
|
Always |
The Ethereum address you wish to give admin rights to for the Comments thread. This user will be able to delete all comments and accept members in a members-only thread. A thread with a new admin address, despite identical spaceName and threadName , will create an entirely new thread. |
box |
Object |
|
A (and likely B) |
The box instance returned from running await Box.openBox(address, web3) somewhere in your dApp. |
currentUserAddr |
String (Ethereum Address) |
|
A & B, optional for C |
The current user's Ethereum address. Passing this will help determine whether a user has delete access on each comment. This prop will also let the component fetch that user's 3Box profile on component mount and render that data (profile picture) in the Comment input UI. |
loginFunction |
Function |
|
B |
A function from your dApp that handles web3 and 3Box login at the global dApp state. This callback will run when a user attempts to save a comment but a box instance doesn't yet exist. Running this function should result in a box instance (from const box = Box.openBox(address, web3) ) being passed as the box prop to this component. |
ethereum |
Object |
window.ethereum |
Always |
The ethereum object from whichever web3 provider your dApp uses. The enable method on this object will be used to get the current user's Ethereum address and that address will be used to openBox within the current Component context. |
members |
Boolean |
False |
Optional |
A boolean - true - to make the thread a members-only thread. Passing false will allow all users to post to the thread. Changing this setting after creating it will result in an entirely different thread (see Docs.3box.io for more info). |
showCommentCount |
Integer |
30 |
Optional |
The number of comments rendered in the UI by default on component mount and the number of additional comments revealed after clicking Load more in component. |
spaceOpts |
Object |
|
Optional |
Optional parameters for threads (see Docs.3box.io for more info) |
threadOpts |
Object |
|
Optional |
Optional parameters for threads (see Docs.3box.io for more info) |
useHovers |
Boolean |
False |
Optional |
Pass true to enable a 3Box profile pop up when hovering over a commenter's name |
currentUser3BoxProfile |
Object |
|
Optional |
If the current user has already had their 3Box data fetched at the global dApp state, pass the object returned from Box.getProfile(profileAddress) to avoid an extra request. This data will be rendered in the Comment input interface. |
userProfileURL |
Function |
Defaults to returning user's 3Box profile URL |
Optional |
A function that returns a correctly formatted URL of a user's profile on the current platform. The function will be passed an Ethereum address within the component, if needed. A user will be redirected to the URL returned from this function when clicking on the name or Ethereum address associated with the comment in the thread. |
Maintainers
@oed
License
麻省理工学院
3box-comments-react
node package is a drop-in react component that provides Web3 developers with a readymade commenting system for their Ethereum application. Easily add rich, decentralized social discourse to your dApp with one line of code. The 3Box Comments plugin is built using 3Box infrastructure, and handles all logic for creating a comments thread. Read the docs on docs.3box.io.
New Social Features:
Replies - reply to comments inline (limited to two levels of replies), deleted comments with nested replies maintain the nested replies
Emoji reactions - react to each comment with emojis from an inline picker
Votes - Upvote or downvote on any comment
Note: This is a breaking change - this will break any previously used comments, to create a new one, simply update the threadName in the same space
How it Works
Architecture
The Comments plugin is built using a standard implementation of Open Threads which are defined in the 3Box Threads API and made available via the 3Box.js SDK
. The Comments plugin also includes UI for inputting and displaying user comments, logic for fetching user profiles, and pagination. The component is configurable to various authentication patterns, and can handle both Web3/3Box logged-in & logged-out states.
Authentication
Without authenticating, users can read messages in the comment thread. However authentication is required to perform more interactive functionality. After the user is authenticated, a user can post a comment, delete their comment, and receive comments from other users in real-time. Note: if you are not logged in and the component has not been passed your ethereum address, the component cannot know which comment belongs to you in order to delete. In this case, click the login button just below the input UI.
Getting Started
- Install the component
- Choose your authentication pattern
- Configure application settings
- Usage
1. Install the component
npm i -S 3box-comments-react
2. Choose your authentication pattern
Depending on when and how your dApp handles authentication for web3 and 3Box, you will need to provide a different set of props to the component. Regardless of the context, the component must be passed either an ethereum provider or the user's box object before it mounts. Three acceptable authentication patterns and their respective props are discussed below in A-C:
A) Dapp handles web3 and 3Box logins, and they run before component is mounted. (recommended)
Dapp integrates with 3Box.js SDK
and the 3box-comments-react
component. In this case, the box
instance returned from Box.openBox(ethAddr)
via 3Box.js should be passed to the box
prop in the comments component. The user's current Ethereum address should be passed to the currentUserAddr
prop to determine deletePost
access on each comment.
B) Dapp handles web3 and 3Box logins, but they haven't run before component is mounted. (recommended)
Dapp integrates with 3Box.js SDK
and the 3box-comments-react
component. In this case, the login logic implemented in the dapp should be passed to the Comments component as the loginFunction
prop, which is run when a user attempts to post a comment. The user's current Ethereum address should be passed to the currentUserAddr
prop to determine deletePost
access on each comment.
C) Dapp has no web3 and 3Box login logic.
Dapp only integrates with the 3box-comments-react
component, but not 3Box.js SDK
. All web3 and 3Box login logic will be handled within the Comments component, though it's required for the ethereum
object from your dapp's preferred web3 provider be passed to the ethereum
prop in the component.
Best practice
For the best UX, we recommend implementing one of the following authentication patterns: A; B; or B with A.
Each of these patterns allow your application to make the box
object available in global application state where it can be used by all instances of the Comments component regardless of which page the user is on. This global pattern removes the need for users to authenticate on each individual page they wish to comment on, which would be the case in C.
First, choose a name for your application's 3Box space.
Although you are free to choose whichever name you'd like for your app's space, we recommend using the name of your app. If your application already has a 3Box space, you are welcome to use that same one for comments.
Next, choose a naming convention for your application's threads.
Comment threads need a name, and we recommend that your application creates threadNames
according to a simple rule. We generally like using a natural identifier, such as community name, page URL, token ID, or other similar means.
Then, create an admin 3Box account for your application.
Each thread is required to have an admin (adminEthAddr
), which possesses the rights to moderate the thread. We recommend you create an admin Ethereum account for your application so you can perform these actions. While technically you can use any Ethereum address as an admin account, we recommend creating a 3Box profile for that address so if you need to take action in the thread, others will know and trust you as the admin.
Lastly, initialize your application's space.
Before threads can be deployed in your dapp, your application's admin account (adminEthAddr
created in the previous step) must first open the space (spaceName
) that will be used to store your application's threads. This step must be completed before your comment threads can be used by others. This process would likely be done outside the context of your dapp, probably in a test environment.
Simply open a space by running (via 3Box.js SDK
):
const box = await Box.openBox(adminEthAddr, ethereum);
const space = await box.openSpace(spaceName, spaceOpts);
Sign the web3 prompts to complete the space initialization process.
4. Usage
Example
import ThreeBoxComments from '3box-comments-react';
const MyComponent = ({ handleLogin, box, ethereum, myAddress, currentUser3BoxProfile, adminEthAddr }) => (
<ThreeBoxComments
// required
spaceName="mySpaceName"
threadName="myThreadName"
adminEthAddr={adminEthAddr}
ethereum={ethereum}
// Required props for context A) & B)
box={box}
currentUserAddr={myAddress}
// Required prop for context B)
loginFunction={handleLogin}
// optional
members={false}
showCommentCount={10}
threadOpts={{}}
useHovers={false}
currentUser3BoxProfile={currentUser3BoxProfile}
userProfileURL={address => `https://mywebsite.com/user/${address}`}
/>
);
Prop Types
Property |
Type |
Default |
Required Case |
Description |
spaceName |
String |
|
Always |
Likely your dApp name and / or comment category. A single spaceName with different threadName s is common practice when building a dApp with multiple Comment threads. |
threadName |
String |
|
Always |
A name specific to this Comments thread. |
adminEthAddr |
String (Ethereum Address) |
|
Always |
The Ethereum address you wish to give admin rights to for the Comments thread. This user will be able to delete all comments and accept members in a members-only thread. A thread with a new admin address, despite identical spaceName and threadName , will create an entirely new thread. |
box |
Object |
|
A (and likely B) |
The box instance returned from running await Box.openBox(address, web3) somewhere in your dApp. |
currentUserAddr |
String (Ethereum Address) |
|
A & B, optional for C |
The current user's Ethereum address. Passing this will help determine whether a user has delete access on each comment. This prop will also let the component fetch that user's 3Box profile on component mount and render that data (profile picture) in the Comment input UI. |
loginFunction |
Function |
|
B |
A function from your dApp that handles web3 and 3Box login at the global dApp state. This callback will run when a user attempts to save a comment but a box instance doesn't yet exist. Running this function should result in a box instance (from const box = Box.openBox(address, web3) ) being passed as the box prop to this component. |
ethereum |
Object |
window.ethereum |
Always |
The ethereum object from whichever web3 provider your dApp uses. The enable method on this object will be used to get the current user's Ethereum address and that address will be used to openBox within the current Component context. |
members |
Boolean |
False |
Optional |
A boolean - true - to make the thread a members-only thread. Passing false will allow all users to post to the thread. Changing this setting after creating it will result in an entirely different thread (see Docs.3box.io for more info). |
showCommentCount |
Integer |
30 |
Optional |
The number of comments rendered in the UI by default on component mount and the number of additional comments revealed after clicking Load more in component. |
spaceOpts |
Object |
|
Optional |
Optional parameters for threads (see Docs.3box.io for more info) |
threadOpts |
Object |
|
Optional |
Optional parameters for threads (see Docs.3box.io for more info) |
useHovers |
Boolean |
False |
Optional |
Pass true to enable a 3Box profile pop up when hovering over a commenter's name |
currentUser3BoxProfile |
Object |
|
Optional |
If the current user has already had their 3Box data fetched at the global dApp state, pass the object returned from Box.getProfile(profileAddress) to avoid an extra request. This data will be rendered in the Comment input interface. |
userProfileURL |
Function |
Defaults to returning user's 3Box profile URL |
Optional |
A function that returns a correctly formatted URL of a user's profile on the current platform. The function will be passed an Ethereum address within the component, if needed. A user will be redirected to the URL returned from this function when clicking on the name or Ethereum address associated with the comment in the thread. |
Maintainers
@oed
License
MIT