ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-20 11:45:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update get started section

Browse Source
This commit is contained in:
mDuo13
2020-08-31 14:28:23 -07:00
parent a809ed03b1
commit c636162a89
4 changed files with 161 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
content/tutorials/get-started/get-started-with-rippleapi-for-javascript.md
View File

@@ -1,6 +1,6 @@
# Get Started with RippleAPI for JavaScript
# Get Started with RippleAPI for Node.js
This tutorial guides you through the basics of building an XRP Ledger-connected application using [Node.js](http://nodejs.org/) and [RippleAPI](rippleapi-reference.html), a JavaScript API for accessing the XRP Ledger.
This tutorial guides you through the basics of building an XRP Ledger-connected application using [Node.js](http://nodejs.org/) and [RippleAPI](rippleapi-reference.html), a JavaScript API for accessing the XRP Ledger. You can also use RippleAPI [straight from your browser](get-started.html).
The scripts and config files used in this guide are [available in the Ripple Dev Portal GitHub Repository](https://github.com/ripple/ripple-dev-portal/tree/master/content/_code-samples/rippleapi_quickstart).
@@ -250,14 +250,34 @@ See [Reliable Transaction Submission](reliable-transaction-submission.html) for
# RippleAPI in Web Browsers
RippleAPI can also be used in a web browser if you compile a browser-compatible version and include [lodash](https://www.npmjs.com/package/lodash) as a dependency before the RippleAPI script.
RippleAPI can also be used in a web browser. To access it, load [Lodash](https://lodash.com/) and [RippleAPI for JavaScript (ripple-lib)](rippleapi-reference.html) in your site's HTML. For example:
<!-- MULTICODE_BLOCK_START -->
_unpkg_
```html
<script src="https://unpkg.com/lodash@4.17.20/lodash.min.js"></script>
<script src="https://unpkg.com/ripple-lib@1.8.0/build/ripple-latest-min.js"></script>
```
_jsDelivr_
```html
<script src="https://cdn.jsdelivr.net/npm/lodash@4.17.20/lodash.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/ripple-lib@1.8.0/build/ripple-latest-min.js"></script>
```
<!-- MULTICODE_BLOCK_END -->
Instead of using Node.js's "require" syntax, the browser version creates a global variable named `ripple`, which contains the `RippleAPI` class.
<!-- SPELLING_IGNORE: lodash -->
## Build a Browser-Compatible Version of RippleAPI
To use RippleAPI in a browser, you need to build a browser-compatible version. The following process compiles RippleAPI into a single JavaScript file you can include in a webpage.
You can also build a browser-compatible version of the code yourself. Use the following steps to build it from the source code.
### 1. Download a copy of the RippleAPI git repository
@@ -285,50 +305,45 @@ yarn
```
### 4. Use Gulp to build a single JavaScript output
### 4. Build with Yarn
RippleAPI comes with code to use the [gulp](http://gulpjs.com/) package to compile all its source code into browser-compatible JavaScript files. Gulp is automatically installed as one of the dependencies, so all you have to do is run it, such as with following command:
RippleAPI comes with the necessary dependencies and code to build it for the browser. Trigger the build script as follows:
```
```sh
yarn run build
```
Output:
```
> ripple-lib@0.16.5 build /home/username/ripple-lib
> gulp
[14:11:02] Using gulpfile /home/username/ripple-lib/gulpfile.js
[14:11:02] Starting 'build'...
[14:11:03] Starting 'build-debug'...
[14:11:03] Starting 'build-min'...
[14:11:18] Finished 'build-debug' after 15 s
[14:11:18] Finished 'build' after 16 s
[14:11:18] Finished 'build-min' after 15 s
[14:11:18] Starting 'default'...
[14:11:18] Finished 'default' after 19 μs
```text
yarn run v1.22.4
$ yarn build:schemas && yarn build:lib && yarn build:web
$ mkdir -p dist/npm/common && cp -r src/common/schemas dist/npm/common/
$ tsc --build
$ webpack
Done in 10.29s.
```
This may take a while. At the end, the build process creates a new `build/` folder, which contains the files you want.
The file `build/ripple-<VERSION NUMBER>.js` is a straight export of RippleAPI (whatever version you built) ready to be used in browsers. The file ending in `-min.js` is the same thing, but with the content [minified](https://en.wikipedia.org/wiki/Minification_%28programming%29) for faster loading. <!-- SPELLING_IGNORE: minified -->
The file `build/ripple-latest.js` is a direct export of RippleAPI (whatever version you built) ready to be used in browsers. The file ending in `build/ripple-latest-min.js` is the same thing, but with the content [minified](https://en.wikipedia.org/wiki/Minification_%28programming%29) for faster loading. <!-- SPELLING_IGNORE: minified -->
## Demo RippleAPI in a Browser
The following HTML file demonstrates basic usage of the browser version of RippleAPI to connect to a public `rippled` server and report information about that server. Instead of using Node.js's "require" syntax, the browser version creates a global variable named `ripple`, which contains the `RippleAPI` class.
The following HTML file demonstrates basic usage of the browser version of RippleAPI to connect to a public `rippled` server and report information about that server.
To use this example, you must first [build a browser-compatible version of RippleAPI](#build-a-browser-compatible-version-of-rippleapi) and then copy one of the resulting output files to the same folder as this HTML file. (You can use either the minified or full-size version.) Change the second `<script>` tag in this example to use the correct file name for the version of RippleAPI you built.
[**browser-demo.html:**](https://github.com/ripple/ripple-dev-portal/blob/master/content/_code-samples/rippleapi_quickstart/browser-demo.html "Source on GitHub")
[**`browser-demo.html`**](https://github.com/ripple/ripple-dev-portal/blob/master/content/_code-samples/rippleapi_quickstart/browser-demo.html "Source on GitHub")
```
{% include '_code-samples/rippleapi_quickstart/browser-demo.html' %}
```
This demo HTML loads Lodash v4.17.11 from CDNJS on Cloudflare and then loads ripple-lib v1.1.2, but you could also download and load a variant of Lodash locally. <!--#{ no specific recommended or required version at this time. Update this once we have some guidance to provide here. }#--> <!-- SPELLING_IGNORE: cdnjs -->
<!-- SPELLING_IGNORE: cdnjs -->
You can also see and edit a similar, live browser demo on the [Get Started](get-started.html) page.
## See Also

78
content/tutorials/get-started/get-started.md
View File

@@ -1,31 +1,54 @@
# Get Started
The XRP Ledger is always online and entirely public. You can access it directly from your browser with [RippleAPI for JavaScript (ripple-lib)](rippleapi-reference.html). Try experimenting with some of the following examples:
The XRP Ledger is always online and entirely public. You can access it **directly from a web browser** with a few steps described in this page. Scroll down to get started!
## 1. Prerequisites
To access the XRP Ledger from a webpage, load [Lodash](https://lodash.com/) and [RippleAPI for JavaScript (ripple-lib)](rippleapi-reference.html) in your site's HTML. For example:
```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.15/lodash.js"></script>
<script src="https://unpkg.com/ripple-lib@1.8.0/build/ripple-latest-min.js"></script>
```
<!-- SPELLING_IGNORE: lodash -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.15/lodash.js"></script>
<script type="application/javascript" src="assets/js/ripple-lib-1.8.0-min.js"></script>
<link rel="stylesheet" type="text/css" href="assets/vendor/codemirror.css"/>
<script type="text/javascript" src="assets/vendor/codemirror-js-json-lint.min.js"></script>
<script src="https://unpkg.com/ripple-lib@1.8.0/build/ripple-latest-min.js"></script>
On this page, that's already done, so continue to the next step!
## 2. First Script
The following code gets the latest [ledger version](ledgers.html) and a list of transactions that were newly-validated in that ledger version, using the [`getLedger()` method](rippleapi-reference.html#getledger). Try running it as-is, or change the code and see what happens.
**Tip:** If you can, open your browser's Developer Tools by pressing **F12**. The "Console" tab provides a native JavaScript console and can give insight into what code is running on any webpage.
<div id="step2">
<pre><code id="step2code">
const mainnet = new ripple.RippleAPI({
server: 'wss://s1.ripple.com' // Ripple's public cluster
// server: 'wss://s2.ripple.com' // Ripple's full history cluster
// server: 'wss://xrpl.ws' // XRPL Labs full history cluster
// server: 'wss://s.altnet.rippletest.net/' // Testnet
// server: 'wss://s.devnet.rippletest.net/' // Devnet
server: 'wss://s1.ripple.com'
});
(async function(api) {
await api.connect();
let ledger = await api.getLedger();
console.log(ledger);
let response = await api.getLedger({
includeTransactions: true
});
console.log(response);
})(mainnet);
</code></pre>
<button type="button" id="step2button" class="btn btn-primary">Run</button>
<p>
<button type="button" id="step2button" class="btn btn-primary">Run</button>
<button type="reset" id="step2reset" class="btn btn-secondary-outline">Reset</button>
</p>
<h3>Output</h3>
<div id="step2resp"></div>
<link rel="stylesheet" type="text/css" href="assets/vendor/codemirror.css" />
<script src="assets/vendor/codemirror-js-json-lint.min.js"></script>
<script type="application/javascript">
const code_ex = $("#step2code");
const code_text = code_ex.text().trim();
@@ -41,7 +64,6 @@ const cm_resp = CodeMirror($("#step2resp").get(0), {
json: false,
readOnly: true
});
let ret;
$("#step2button").click((evt) => {
const oldconsole = console;
@@ -53,4 +75,32 @@ $("#step2button").click((evt) => {
}
Function(cm.getValue())();
});
$("#step2reset").click((evt) => {
cm.setValue(code_text);
});
function fill_ex_1() {
cm.setValue("const mainnet = new ripple.RippleAPI({\n server: 'wss://s.altnet.rippletest.net/'\n});\n\n(async function(api) {\n await api.connect();\n\n let response = await api.getLedger({\n includeTransactions: true\n });\n console.log(response);\n\n})(mainnet);");
$("html").animate({scrollTop: $("#step2").offset().top}, 500);
}
function fill_ex_2() {
cm.setValue("const mainnet = new ripple.RippleAPI({\n server: 'wss://s1.ripple.com'\n});\n\n(async function(api) {\n await api.connect();\n\n let response = await api.getLedger({\n includeTransactions: true\n });\n let tx_id = response.transactionHashes[0];\n let response2 = await api.getTransaction(tx_id);\n console.log(response2);\n\n})(mainnet);");
$("html").animate({scrollTop: $("#step2").offset().top}, 500);
}
function fill_ex_3() {
cm.setValue("const mainnet = new ripple.RippleAPI({\n server: 'wss://s1.ripple.com'\n});\n\n(async function(api) {\n await api.connect();\n\n let response = await api.getLedger({\n includeTransactions: true\n });\n console.log('Total XRP: '+api.dropsToXrp(response.totalDrops));\n\n})(mainnet);");
$("html").animate({scrollTop: $("#step2").offset().top}, 500);
}
</script>
</div>
## 3. Next Steps
Try editing the code from step 2 to do something different:
- Connect to the [Testnet](parallel-networks.html) public server at `wss://s.altnet.rippletest.net/` instead. [Answer >](javascript:fill_ex_1())
- Look up the details of a transaction using the [`getTransaction()` method](rippleapi-reference.html#gettransaction). For the `id`, use one of the `transactionHashes` from the `getLedger()` response! [Answer >](javascript:fill_ex_2())
- Convert the `totalDrops` from the response to decimal XRP. [Answer >](javascript:fill_ex_3())
## Further Reading
<!--{# Followed by bullet points automatically generated by the landing template #}-->