Skip to content

Commit

Permalink
Update examples (#1725)
Browse files Browse the repository at this point in the history 
* fix: always cache translations & docusaurus cache

* feat: change repo examples

* temp

* temp

* temp

* feat: update url for example

* Change url for examples

* feat: change donation example

* set structure for examples

* update donation example

* Update docs/3.tutorials/examples/donation.md

* temp

* update examples

* update examples

* Apply suggestions from code review

* delete unsed asset

* fix assets

* minor fixes

---------

Co-authored-by: gagdiez <gagdiez.c@gmail.com>
Co-authored-by: Matias Benary <matiasbenary@gmai.com>
Co-authored-by: Damián Parrino <bucanero@users.noreply.github.com>
  • Loading branch information
@matiasbenary @gagdiez @bucanero
4 people authored Feb 12, 2024
1 parent ca46bbf commit 83ab808
Show file tree
Hide file tree
Showing 203 changed files with 361 additions and 740 deletions.
2 changes: 1 addition & 1 deletion docs/2.develop/testing/integration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ Lets take a look at the test of our [Quickstart Project](../quickstart.md) [👋

## Snippet II: Testing Donations

In most cases we will want to test complex methods involving multiple users and money transfers. A perfect example for this is our [Donation Example](https://github.com/near-examples/donation-js), which enables users to `donate` money to a beneficiary. Lets see its integration tests:
In most cases we will want to test complex methods involving multiple users and money transfers. A perfect example for this is our [Donation Example](https://github.com/near-examples/donation-examples), which enables users to `donate` money to a beneficiary. Lets see its integration tests

<CodeTabs>
<Language value="🌐 JavaScript" language="js">
Expand Down
220 changes: 156 additions & 64 deletions docs/3.tutorials/examples/count-near.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
id: count-near
title: Count on NEAR
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import {CodeTabs, Language, Github} from "@site/src/components/codetabs"
Expand All @@ -13,64 +14,109 @@ Our counter example is a friendly decentralized app that stores a number and exp

---

## Starting the Counter
## Obtaining the Counter Example

You have two options to start the Counter Example.

1. You can use the app through `GitHub Codespaces`, which will open a web-based interactive environment.
2. Clone the repository locally and use it from your computer.

| Codespaces | Clone locally |
| ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/near-examples/counters) | 🌐 `https://github.com/near-examples/counters` |

---

You have two options to start the Counter:
## Structure of the Example

1. **Recommended:** use the app through Gitpod (a web-based interactive environment)
2. Clone the project locally .
The example is divided in two main components:

1. The smart contract, available in two flavors: Rust and JavaScript
2. The frontend, that interacts with an already deployed contract.

<Tabs>

<Tabs className="language-tabs" groupId="code-tabs">
<TabItem value="🌐 JavaScript">

| Codespaces | Clone locally |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/near-examples/counters) | 🌐 `https://github.com/near-examples/js-counter.git` |
```bash
┌── sandbox-ts # sandbox testing
│ ├── src
│ │ └── main.ava.ts
│ ├── ava.config.cjs
│ └── package.json
├── src # contract's code
│ └── contract.ts
├── package.json # package manager
├── README.md
└── tsconfig.json # test script
```

</TabItem>

<TabItem value="🦀 Rust">

| Codespaces | Clone locally |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/near-examples/counters) | 🦀 `https://github.com/near-examples/rust-counter.git` |
```bash
┌── sandbox-ts # sandbox testing
│ ├── src
│ │ └── main.ava.ts
│ ├── ava.config.cjs
│ └── package.json
├── src # contract's code
│ └── lib.rs
├── build.sh # build script
├── Cargo.toml # package manager
├── README.md
└── rust-toolchain.toml
```

</TabItem>

</Tabs>

If you choose Gitpod, a new browser window will open automatically with the code. Give it a minute, and the frontend will pop up (ensure the pop-up window is not blocked).
---

## Frontend

The counter example includes a frontend interface designed to interact seamlessly with an existing smart contract that has been deployed. This interface allows users to increase or decrease the counter as needed.

<hr class="subsection" />

### Running the Frontend

If you are running the app locally, enter the directory where you cloned it and use `yarn` to install dependencies, and `yarn start` to start it.
To start the frontend you will need to install the dependencies and start the server.

```bash
cd counter
cd frontend
yarn
yarn deploy
yarn start
```

Your contract will then be **compiled** and **deployed** to an **account** in the `testnet` network. When done, a browser window should open.
Go ahead and login with your NEAR account. If you don't have one, you will be able to create one in the moment. Once logged in, use the `+` and `-` buttons to increase and decrease the counter. Then, use the Gameboy buttons to reset it and make the counter blink an eye!

---
![img](/docs/assets/examples/count-on-near.png)
_Frontend of the Counter_

## Interacting With the Counter
<hr class="subsection" />

Go ahead and login with your NEAR account. If you don't have one, you will be able to create one in the moment. Once logged in, use the `+` and `-` buttons to increase and decrease the counter. Then, use the Gameboy buttons to reset it and make the counter blink an eye!
### Understanding the Frontend

![img](/docs/assets/examples/count-on-near.png)
*Frontend of the Counter*
The frontend is composed by a single HTML file (`/index.html`). This file defines the components displayed in the screen.

---
The website's logic lives in `/index.js`, which communicates with the contract through `/near-wallet.js`. You will notice in `/index.js` the following code:

## Structure of a dApp
<CodeTabs>
<Language value="🌐 JavaScript" language="ts">
<Github fname="index.js"
url="https://github.com/near-examples/counters/blob/main/frontend/index.js"
start="10" end="21" />
</Language>
</CodeTabs>

Now that you understand what the dApp does, let us take a closer look to its structure:
It indicates our app, when it starts, to check if the user is already logged in and execute either `signedInFlow()` or `signedOutFlow()`.

1. The frontend code lives in the `/frontend` folder.
2. The smart contract code is in the `/contract` folder.
---

### Contract
## Smart Contract

The contract presents 4 methods: `get_num`, `increment`, `decrement`, and `reset`. The method `get_num` retrieves the current value, and the rest modify it.

Expand All @@ -87,56 +133,102 @@ The contract presents 4 methods: `get_num`, `increment`, `decrement`, and `reset
</Language>
</CodeTabs>

### Frontend
---

The frontend is composed by a single HTML file (`/index.html`). This file defines the components displayed in the screen.
### Testing the Contract

The website's logic lives in `/assets/js/index.js`, which communicates with the contract through `/near-interface.js`. You will notice in `/assets/js/index.js` the following code:
The contract readily includes a set of unit and sandbox testing to validate its functionality. To execute the tests, run the following commands:

<CodeTabs>
<Language value="🌐 JavaScript" language="ts">
<Github fname="index.js"
url="https://github.com/near-examples/counters/blob/main/frontend/index.js"
start="10" end="21" />
</Language>
</CodeTabs>
<Tabs>
<TabItem value="🌐 JavaScript">

It indicates our app, when it starts, to check if the user is already logged in and execute either `signedInFlow()` or `signedOutFlow()`.
```bash
cd contract-ts
yarn
yarn test
```

---
</TabItem>
<TabItem value="🦀 Rust">

```bash
cd contract-rs
./test.sh
```

## Testing
</TabItem>

When writing smart contracts it is very important to test all methods exhaustively. In this
project you have two types of tests: unit and integration. Before digging in them,
go ahead and perform the tests present in the dApp through the command `yarn test`.
</Tabs>

### Unit test
:::tip
The `integration tests` use a sandbox to create NEAR users and simulate interactions with the contract.
:::

Unit tests check individual functions in the smart contract. Right now only Rust implements unit testing.
<hr class="subsection" />

<CodeTabs>
<Language value="🦀 Rust" language="rust">
<Github fname="lib.rs"
url="https://github.com/near-examples/counters/blob/main/contract-rs/src/lib.rs"
start="48" end="69" />
</Language>
</CodeTabs>
### Deploying the Contract to the NEAR network

### Integration test
In order to deploy the contract you will need to [create a NEAR account](/develop/contracts/quickstart#create-a-testnet-account).

Integration tests are generally written in javascript. They automatically deploy a new
contract and execute methods on it. In this way, integration tests simulate interactions
from users in a realistic scenario. You will find the integration tests for the `counter`
in `tests/integration-tests`.
<Tabs>
<TabItem value="🌐 JavaScript">

<CodeTabs>
<Language value="🌐 JavaScript" language="ts">
<Github fname="main.test.js"
url="https://github.com/near-examples/counters/blob/main/contract-ts/sandbox-ts/src/main.ava.ts"
start="37" end="61" />
</Language>
</CodeTabs>
```bash
# Optional - create an account
near create-account <accountId> --useFaucet
# Deploy the contract
cd contract-ts
yarn build
near deploy <accountId> ./build/counter.wasm
```

</TabItem>
<TabItem value="🦀 Rust">

```bash
# Optional - create an account
near create-account <accountId> --useFaucet
# Deploy the contract
cd contract-rs
./build.sh
near deploy <accountId> ./target/wasm32-unknown-unknown/release/counter.wasm
```

</TabItem>
</Tabs>

:::tip
To interact with your contract from the [frontend](#frontend), simply replace the variable `CONTRACT_NAME` in the `index.js` file.
:::

<hr class="subsection" />

### CLI: Interacting with the Contract

To interact with the contract through the console, you can use the following commands

```bash
# Get the current number of the counter
near view counter.near-examples.testnet get_num
# Increment the counter
# Replace <accountId> with your account ID
near call counter.near-examples.testnet increment --accountId <accountId>
# Decrement the counter
# Replace <accountId> with your account ID
near call counter.near-examples.testnet decrement --accountId <accountId>
# Reset the counter to zero
# Replace <accountId> with your account ID
near call counter.near-examples.testnet reset --accountId <accountId>
```

:::tip
If you're using your own account, replace `counter.near-examples.testnet` with your `accountId`.
:::
---
Expand Down
41 changes: 35 additions & 6 deletions docs/3.tutorials/examples/donation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,6 @@ The example is divided in two main components:
│ │ └── main.ava.ts
│ ├── ava.config.cjs
│ └── package.json
├── package.json
├── src # contract's code
│ ├── contract.ts
│ ├── model.ts
Expand Down Expand Up @@ -103,7 +102,7 @@ Go ahead and login with your NEAR account. If you don't have one, you will be ab

### Understanding the Frontend

The frontend is composed by a single HTML file (`/index.html`), while the logic lives in `/assets/js/index.js`, which communicates with the contract through `/assets/js/near/utils.js`.
The frontend is composed by a single HTML file (`/index.html`), while the logic lives in `/index.js`, which communicates with the contract through `/near-interface.js`.

<Language value="" language="js">
<Github fname="index.js"
Expand Down Expand Up @@ -180,18 +179,26 @@ In order to deploy the contract you will need to [create a NEAR account](/develo
<TabItem value="🌐 JavaScript">

```bash
# Optional - create an account
near create-account <accountId> --useFaucet
# Deploy the contract
cd contract-ts
yarn build
near deploy <accountId> ./build/contract.wasm
near deploy <accountId> ./build/donation.wasm
```

</TabItem>
<TabItem value="🦀 Rust">

```bash
# Optional - create an account
near create-account <accountId> --useFaucet
# Deploy the contract
cd contract-rs
./build.sh
near deploy <accountId> ./target/wasm32-unknown-unknown/release/contract.wasm
near deploy <accountId> ./target/wasm32-unknown-unknown/release/donation.wasm
```

</TabItem>
Expand All @@ -205,11 +212,33 @@ To interact with your contract from the [frontend](#frontend), simply replace th

### CLI: Interacting with the Contract

To interact with the contract through the console, you can use the following commands

```bash
near view donation.near-examples.testnet get_donations
near call donation.near-examples.testnet donate --accountId <accountId> --deposit 0.1 -->
# Get donations
# Optional arguments for pagination
near view donation.near-examples.testnet get_donations --args='{"from_index": "0","limit": "10"}'
# Get beneficiary
near view donation.near-examples.testnet get_beneficiary
# Get number of donors
near view donation.near-examples.testnet number_of_donors
# Get donation for an account
# Require accountId
near view donation.near-examples.testnet get_donation_for_account --args='{"account_id":<accountId>}'
# Donate to the contract
# Replace <accountId> with your account ID
# Require deposit
near call donation.near-examples.testnet donate --accountId <accountId> --deposit 0.1
```

:::tip
If you're using your own account, replace `donation.near-examples.testnet` with your `accountId`.
:::
---
## Moving Forward
Expand Down
Loading

0 comments on commit 83ab808

Please sign in to comment.