import Tabs from ‘@theme/Tabs’;
import TabItem from ‘@theme/TabItem’;
VM provides a convenient API to get data from the SocialDB contract. There are four methods:
Social.get
Social.get
fetches the data from the SocialDB contract by callingget
and returns the data.- While the data is fetching the returned value equals to
null
. -
::note
If the path pattern is a single key, it will try to unwrap the object until the first wildcard. - ::
The method takes up to 3 arguments:
param | required | type | description |
---|---|---|---|
patterns |
required | string / string[] | the path pattern(s) |
finality |
optional | "final" / number |
the block height or finality |
options |
optional | object | the options object. |
:::info options object
subscribe
(optional): if true, the data will be refreshed every 5 seconds.return_deleted
(optional): whether to return deleted values (asnull
). Default isfalse
.
:::
The block height or finality can be used to get the data at a specific block height or finality.
If the block height or finality is not specified, the data will be fetched at the optimistic
finality (the latest block height).
For block height and finality final
, instead of calling the NEAR RPC directly, the VM uses the Social API Server to fetch the data.
Social API server indexes the data for SocialDB and allows to fetch the data at any block height with additional options.
It also allows returning more data than an RPC call because it’s not restricted by the gas limit.
In general, the API server also serves data faster than the NEAR RPC, because it doesn’t execute the contract code in a virtual machine.
Social.get
options are similar to the SocialDB’s get
API.
Examples
For example, if the path pattern is mob.near/widget/*
, the Social.get
will unwrap the object and return the following:
“`js
const data = Social.get(“mob.near/widget/*”);
“`
“`json
{
“HelloWorld”: “return
;”,
“HelloUsername”: “return
;”
}
“`
If the path pattern is mob.near/widget/HelloWorld
, the Social.get
will unwrap the object and return the actual value:
“`js
const data = Social.get(“mob.near/widget/HelloWorld”);
“`
“`json
“return
;”
“`
It’s helpful that you don’t have to manually unwrap object.
Social.getr
Social.getr
is just a wrapper helper for Social.get
, it appends **
to each of the path pattern.
param | required | type | description |
---|---|---|---|
patterns |
required | string / string[] | the path pattern(s) |
finality |
optional | "final" / number |
the block height or finality |
options |
optional | object | the options object. |
:::info options object
subscribe
(optional): if true, the data will be refreshed every 5 seconds.return_deleted
(optional): whether to return deleted values (asnull
). Default isfalse
.
:::
Examples
For example, if the path pattern is mob.near/profile
, Social.getr
will call Social.get
with the path pattern mob.near/profile/**
.
“`js
const data = Social.getr(“mob.near/profile”);
“`
“`json
“return
;”
“`
Social.keys
It calls the SocialDB’s keys
API and returns the data. While the data is fetching the returned value equals to null
.
The keys contract doesn’t unwrap the object, so the returned data is the same as the SocialDB’s keys
API.
Social.keys
takes up to 3 arguments:
param | required | type | description |
---|---|---|---|
patterns |
required | string / string[] | the path pattern(s) |
finality |
optional | "final" / number |
the block height or finality |
options |
optional | object | the options object. |
:::info options object
subscribe
(optional): if true, the data will be refreshed every 5 seconds.return_type
(optional): either"History"
,"True"
, or"BlockHeight"
. If not specified, it will return the"True"
.return_deleted
(optional): whether to return deleted values (asnull
). Default isfalse
.values_only
(optional): whether to return only values (don’t include objects). Default isfalse
.
- :::
-
::tip
The Social API server supports custom optionsreturn_type: "History"
. For each matching key, it will return an array containing all the block heights when the value was changed in ascending order.
It can be used for building a feed, where the values are overwritten. - ::
Examples
“`js
const data = Social.keys(`${accountId}/post/meme`, “final”, {
return_type: “History”,
});
“`
“`json
“return
;”
“`
Social.index
Returns the array of matched indexed values. Ordered by blockHeight
.
Social.index
arguments:
param | required | type | description |
---|---|---|---|
action |
required | string | is the index_type from the standard, e.g. in the path index/like the action is like . |
key |
required | string | is the inner indexed value from the standard. |
options |
optional | object | the options object. |
:::info options object
subscribe
(optional): if true, the data will be refreshed every 5 seconds.accountId
(optional): If given, it should either be a string or an array of account IDs to filter values by them. Otherwise, not filters by account Id.order
(optional): Eitherasc
ordesc
. Defaults toasc
.limit
(optional): Defaults to100
. The number of values to return. Index may return more than index values, if the last elements have the same block height.from
(optional): Defaults to0
orMax
depending on order.
:::
Examples
“`jsx
return Social.index(“test”, “test-key-2”);
“`
“`jsx
return Social.index(“test”, “test-key-2”, {
accountId: “mob.near”
});
“`
“`jsx
return Social.index(“test”, “test-key-2”, {
accountId: [“mob.near”, “root.near”]
});
“`
“`json
[
{
“accountId”: “mob.near”,
“blockHeight”: 78672789,
“value”: “test-value-1”
},
{
“accountId”: “mob.near”,
“blockHeight”: 78672797,
“value”: “test-value-1”
},
{
“accountId”: “mob.near”,
“blockHeight”: 78672974,
“value”: “test-value-3”
}
]
“`
Social.set
Takes a data
object and commits it to SocialDB. It works similarly to
the CommitButton
by spawning the modal window prompt to save data, but
it doesn’t have to be triggered through the commit button component. It
allows you to write more flexible code that relies on async promises and
use other events and components. Overall it enables more flexibility
when committing to SocialDB. For example, you can commit when Enter key
pressed.
Social.set
arguments:
param | required | type | description |
---|---|---|---|
data |
required | object | the data object to be committed. Similar to CommitButton , it shouldn’t start with an account ID. |
options |
optional | object | optional object. |
:::info options object
force
(optional): whether to overwrite the data.onCommit
(optional): function to trigger on successful commit. Will pass the
data that was written (includingaccountID
).onCancel
(optional): function to trigger if the user cancels the commit.
:::
Ability to skip confirmation
When a modal window to confirm a commit is shown, it has a toggle to
select whether you want to confirm the action every time, or don’t show
the confirm window for similar data.
- By default for new data the toggle is set to on, which means the user will not be prompted to
- confirm the data for the next time. It remembers the decision locally
- and will be default to this decision next time (in case the user decides
- to not skip). If the user approves the commit with the toggle on, then the
- next commit with similar data will skip the confirmation window. The
- permission is given per widget source.
-
::note
- Similar data means the same top level keys on the data. Except for the
- 4 top level keys:
graph
,post
,index
andsettings
. For these - keys, the second level key will be used. More keys can be added later,
- once new standards added.
-
::
For example the follow button widget uses the following keys:
{
"graph": {
"follow": ...
},
"index": {
"graph": ...
"notify": ...
}
}
If it attempts to modify something else, the confirmation modal will be
shown again.
Examples
Example on using CommitButton
and Social.set
with a regular button.
Note, both use force
“`jsx
State.init({ commitLoading: false });
const data = { experimental: { test: “test” } };
const Loading = (
);
return (
CommitButton
);
“`