Quickstart

This tutorial will help you do your first steps with a simple example app. Once you are done you should be able to understand the basic functionality of Plugged and how it works on the surface. From there you can start your project and keep the reference up to help you with functions.

Requirements

Before we start let me get some requirements set, so you don’t experience any hiccups.

To finish this tutorial you should have:

  1. A working Computer
  2. Node installed in version 6.6+
  3. a cmd you like to use
  4. an editor, personally I recommend VS Code or SublimeText
  5. 20 minutes

Once we got that checked, let’s go on.

Getting started

To get you started without much hassle, we first need to determine which operating system you use. So just click on one of the listed below so we can get to the meat.

To start you should first open PowerShell (if you’re using windows) or bash. Now you should be in your home directory, so you start by creating a folder by entering the following two lines:

mkdir getplugged
cd getplugged

Now you should be in your project directory. So the next up is that we ask npm to initialize a new project for us, this can be done easily by entering:

npm init

Now you will be asked a few questions about your project. Most information on the questions can be found out by checking out google real quick. Now I would do a walkthrough to that too, but npm might change over time and has already changed a lot in between node versions so I will just stay quiet and wait for you here. Yes, go on, no haste.

Now that you initialized the project we will need to pull in Plugged as a dependency. We can do this by entering:

npm install --save plugged

The –save is there to add a line in your dependencies object in package.json

Next you should create a new file to create our bot in. In this example we’ll use the name bot.js for it.

Getting to code

Alright, on to the good part. Now we start programming our example. First off we need to get access to our Plugged dependency. This is done by writing:

const Plugged = require("plugged");

Perfect! Now we need to create our bot class, we do this by writing down the following lines:

class OurSuperAwesomeBot extends Plugged {
    constructor(options={}) {
        super(options);
    }
}

module.exports = OurSuperAwesomeBot;

Now that we got this set, I’ll explain some things. What we did here is to inherit Plugged into our bot class. So we have access to all its functions through this… t.. the keyword, I mean.

the options argument passed in the constructor enables you to pass several startup settings to Plugged as shown here .

The last line is just us using CommonJS to export our class so we can pull it in with require later.

Next we should flesh out our bot class so that it is able to greet people. For that we need something to make it say something and, as we all know, What is better for that than a function? Time to extend our class!

class OurSuperAwesomeBot extends Plugged {
    constructor(options={}) {
        super(options);
    }

    // here we add our new code
    greet(user) {
        this.sendChat(`Hi, @${user.username}`);
    }
}

The greet function will accept a User object as parameter. We will use this to identicate the user we want to greet.

The next line uses the sendChat function to send a message in chat. As parameter, we define a template string in which we use the user object to identify who we want to greet. While the ${ … } is syntax relevant to implement a variable in a template string, the @ is not. It is just there to make plug notify the user about our message.

And thus, we’re done with our bot class! Yes, that’s it, but don’t wipe your sweat so soon. There’s one part remaining, The wire up!

You probably figured that something is still missing and thought: “but we need to call that function somewhere” yes, you are absolutely right! We will come to this now.

To get a little more precise about it, we need to think about what we want to achieve in this last part, to summarize our problem we stand in front of:

how do we figure out when a new user joins the room, also how do we connect to plug.dj and a room

This is relatively easy thanks to Plugged! Which is also why we are already done with our bot class. Remember that we inherited Plugged into our class? We inherited all functionality of Plugged with it into our Bot class, so our bot class is not just one function big, but it has plenty of functionality already built in thanks to this inheritance of which we will make use now!

So hit up your editor and create a new file called app.js and write down the following code:

const OurSuperAwesomeBot = require("./bot");
const bot = new OurSuperAwesomeBot();

/**
* note: you need to change the email and password to your own,
* it has to be a second account.
* Otherwise you won't see the message in the end!
*/
bot.login({
    email: "example@examplehost.moe",
    password: "examplepassword"
});

Alright to explain this part, in the first line we do what we did in bot.js already with Plugged. We pull in a reference to our bot class. The next line creates a new instance of our super awesome bot class.

Since we created a new instance of our bot we are now able to use its functionality which will help us solve one of our problems directly.

The login function logs us with our credentials into plug, after that we’re able to join rooms and use other non room related functions.

Next we need to wire everything to the respective event. Plugged uses a lot of events. I am not kidding. There’s plenty of actions that erupt as events, but that’s a topic for another time, so we’ll just need one event which is:

Using events is as simple as using the functions on and once

const OurSuperAwesomeBot = require("./bot");
const bot = new OurSuperAwesomeBot();

// NEW CODE HERE
const loggedIn = function(err, self) {
    if (!err)
        bot.connect("exampleroom", joinedRoom); // change exampleroom into your room of choice
    else
        console.log(err);
};

const joinedRoom = function(err, room) {
    if (!err) {
        console.log("connected to room!");
        bot.on("USER_JOIN", user => bot.greet(user));
    } else {
        console.log(err);
    }
}

bot.login({
    email: "example@examplehost.moe",
    password: "examplepassword"
}, loggedIn);

To explain the last part, what we did here is to add a callback to the login function, which allows us to connect to the room we want to with connect. The parameter we gave it is the name of the room we want to connect to.

In the callback of connect we once again log an output to the console so we know we are actually connected to our room. The last new part includes the registration of the our greet function on the USER_JOIN event, which passes a User object to the function.

And we’re done! Yep, that’s it! Time to let it run and see how it does. Save your files and open a commandline window, now type

cd path/to/our/bot
node app.js

this will start up our bot, next up is to go to the room you passed in as a parameter on connect and you should see your bot greeting you by your username!

Congratulations, you just wrote your first bot for plug.dj!

Where to go from here

I hope I could fire you a bit up for your own steps into this and get all tingly for a project. In case you haven’t had any ideas yet, you should check out the notable mentions page. It contains some of the projects that use Plugged. Also there’s the possibility for you to check out the cookbook which contains examples for various use cases as well as best practices for Plugged.

PS: this will likely become your new best friend on your journey