Docs BETA
/

4. Quick Start

Get your code on a machine


This quick start guide is intended to get you up and running deploying working code to your machine within 15 minutes. We assume you have npm installed and have a basic understanding of Javascript ES6.

If you would like to skip the tutorial and work through it yourself then either download the .zip here or copy and paste the below into your terminal

git clone https://github.com/vendOS-io/QuickStart

1. Download the package

All machine communication can be done with our simple promise based package called vendOS. You can download the minified file here

https://raw.githubusercontent.com/vendOS-io/vendOS-js/master/lib/vendos.min.js

We are going to do the rest of this guide using the minified download, but if you are integrating into a larger project you can use NPM like below:

npm install --save vendos

2. Create a Project Folder and Files

All thats needed to get going is an index.html page and the vendos package, but we are going to layout this example project in a standard manner.

Create the below file structure:

QuickStart/
├── js/
├───── vendos.min.js
├───── main.js
├── css/
├───── style.css
├── index.html

3. Set up the HTML

We have scaffolded out a very simple page below.

Note: We always recommend keeping things simple on the machine. For example, there is no need to have selectable text, rollover states, seo optimisation, responsive design etc. etc. Its good to keep in mind that your code is just sitting on the machine running in a single browser and the window is always the same size!

<!-- File: index.html -->
<html>
    <head>
        <link href="./css/style.css" type="text/css" rel="stylesheet"> <!-- Import the stylesheet -->
        <script src="./js/vendos.min.js"></script> <!-- Import the package -->
    </head>
    <body>
        <div class="error-display" id="error"></div> <!-- Error box -->

        <div class="vend-button" id="vend">VEND</div> <!-- Vend button -->

        <script src="./js/main.js"></script> <!-- Import the javascript -->
    </body>
</html>

3. Initial configuration

When creating the vendOS instance you can pass a variety of initial settings to be applied to the base machine. All options are explored in the 'Configuration' section of this documentation. For now we will roll with the defaults.

// File: js/main.js
const OS = new vendOS()

4. Vending

For the sake of ease we have just used vanilla javascript to get you up and running quickly.

You can see in the below example that we just have an event listener for the vend button and then we call the OS.Machine.randomVend promise.

Note: We have many types of vend requests and options for them, please check it all out in the 'vending' section of this documentation.

The .then will be called after a successful vend has taken place. The .catch block will catch errors in the formation of your query, for example if you were using channelVend and called a channel that does not exist.

Important Note: The .catch on vend requests only catches developer errors, all other hardware errors (such as the machine jamming) get caught and displayed by vendOS.

// File: js/main.js
const OS = new vendOS()

button.addEventListener("click", ()=>{

    OS.Machine.randomVend().then(()=>{

    }).catch((e)=>{
    
    })
})

5. User Feedback

Whilst the machine is vending you want your users to know whats going on, you also don't want them to issue more than one vend at a time. So below we have kept it simple and just changed the text of the button to VENDING, added a class so it no longer looks selectable and put a conditional in so they cannot click the VEND button whilst the vend is already in progress. There is then a timeout of 5 seconds to revert the button back to its initial state and allow vending once again.

We have also added an error display so you can see if your queries are properly formatted, you would not include this in a production build.

// File: js/main.js
const OS = new vendOS()

let button = document.getElementById("vend")
let error = document.getElementById("error")

button.addEventListener("click", ()=>{
    if(button.classList.contains("working")){
        
        button.classList.toggle("working");

        button.innerHTML = "VENDING"

        OS.Machine.randomVend().then(()=>{

            button.innerHTML = "VENDED"

            setTimeout(()=>{
                button.classList.toggle("working");

                button.innerHTML = "VEND"
            }, 5000)

        }).catch((e)=>{
            button.classList.toggle("working");

            error.innerHTML = `<p>${e}</p>`
        })
    }
})

6. Style

We have just put a simple stylesheet together for ease. Its nothing complicated and not really part of this quick start tutorial, but included below regardless!

/* File: css/style.css */

body {
    font-family: Arial, Helvetica, sans-serif;
    margin: 0;
    width: 1080px;
    height: 1920px;
}

/* Error display box, in reality you would not include this on a production deploy */

.error-display {
    position: absolute;
    top: 20px;
    left: 20px;
    width: calc(100% - 80px);
    background: #ff9292;
    font-family: monospace;
    font-size: 1.5em;
    color: #fff;
}


.error-display p {
    padding: 20px;
}

/* Vend button styling */

.vend-button {
    position: absolute;
    top: calc(50% - 50px);
    left: calc(50% - 200px);
    width: 400px;
    height: 100px;
    border: 3px solid #000;
    text-align: center;
    line-height: 100px;
    font-size: 2em;
}

.working {
    opacity: 0.6;
    background: #000;
    color: #fff;
}

7. Uploading

Finally once you have everything together its time to upload!

  1. Zip up your project directory (if using react or another frontend framework don't forget to build first and then upload the build directory!)
  2. Navigate to your provided upload link (if you do not have one, please email [email protected])
  3. Click the cloud icon and select your local zipped folder
  4. Wait for the 'SUCCESSFUL UPLOAD' message
  5. The machine will automatically switch over to the new files
  6. Have a go with your new app!

Graph layer