From d7e7803178eb4be7507df694e168a582b87d1218 Mon Sep 17 00:00:00 2001 From: Isabella Date: Thu, 26 Apr 2018 01:13:44 -0500 Subject: [PATCH] docs: (backport) Bring the main doc pages up to date, and add more examples (#2094) --- docs/examples/attachments.md | 163 +++++++++++++++++++++++++++++++++++ docs/examples/avatars.js | 19 ++-- docs/examples/embed.js | 38 ++++++++ docs/examples/greeting.js | 19 ++-- docs/examples/moderation.md | 145 +++++++++++++++++++++++++++++++ docs/examples/ping.js | 19 ++-- docs/examples/webhook.js | 6 +- docs/general/faq.md | 4 +- docs/general/welcome.md | 1 + docs/index.yml | 6 ++ docs/topics/voice.md | 6 +- 11 files changed, 390 insertions(+), 36 deletions(-) create mode 100644 docs/examples/attachments.md create mode 100644 docs/examples/embed.js create mode 100644 docs/examples/moderation.md diff --git a/docs/examples/attachments.md b/docs/examples/attachments.md new file mode 100644 index 000000000..292f964c9 --- /dev/null +++ b/docs/examples/attachments.md @@ -0,0 +1,163 @@ +# Sending Attachments + +In here you'll see a few examples showing how you can send an attachment using discord.js. + +## Sending an attachment using a URL + +There are a few ways you can do this, but we'll show you the easiest. + +The following examples use [Attachment](/#/docs/main/stable/class/Attachment). + +```js +// Extract the required classes from the discord.js module +const { Client, Attachment } = require('discord.js'); + +// Create an instance of a Discord client +const client = new Client(); + +/** + * The ready event is vital, it means that only _after_ this will your bot start reacting to information + * received from Discord + */ +client.on('ready', () => { + console.log('I am ready!'); +}); + +client.on('message', message => { + // If the message is '!rip' + if (message.content === '!rip') { + // Create the attachment using Attachment + const attachment = new Attachment('https://i.imgur.com/w3duR07.png'); + // Send the attachment in the message channel + message.channel.send(attachment); + } +}); + +// Log our bot in using the token from https://discordapp.com/developers/applications/me +client.login('your token here'); +``` + +And here is the result: + +![Image showing the result](/static/attachment-example1.png) + +But what if you want to send an attachment with a message content? Fear not, for it is easy to do that too! We'll recommend reading [the TextChannel's "send" function documentation](/#/docs/main/stable/class/TextChannel?scrollTo=send) to see what other options are available. + +```js +// Extract the required classes from the discord.js module +const { Client, Attachment } = require('discord.js'); + +// Create an instance of a Discord client +const client = new Client(); + +/** + * The ready event is vital, it means that only _after_ this will your bot start reacting to information + * received from Discord + */ +client.on('ready', () => { + console.log('I am ready!'); +}); + +client.on('message', message => { + // If the message is '!rip' + if (message.content === '!rip') { + // Create the attachment using Attachment + const attachment = new Attachment('https://i.imgur.com/w3duR07.png'); + // Send the attachment in the message channel with a content + message.channel.send(`${message.author},`, attachment); + } +}); + +// Log our bot in using the token from https://discordapp.com/developers/applications/me +client.login('your token here'); +``` + +And here's the result of this one: + +![Image showing the result](/static/attachment-example2.png) + +## Sending a local file or buffer + +Sending a local file isn't hard either! We'll be using [Attachment](/#/docs/main/stable/class/Attachment) for these examples too. + +```js +// Extract the required classes from the discord.js module +const { Client, Attachment } = require('discord.js'); + +// Create an instance of a Discord client +const client = new Client(); + +/** + * The ready event is vital, it means that only _after_ this will your bot start reacting to information + * received from Discord + */ +client.on('ready', () => { + console.log('I am ready!'); +}); + +client.on('message', message => { + // If the message is '!rip' + if (message.content === '!rip') { + // Create the attachment using Attachment + const attachment = new Attachment('./rip.png'); + // Send the attachment in the message channel with a content + message.channel.send(`${message.author},`, attachment); + } +}); + +// Log our bot in using the token from https://discordapp.com/developers/applications/me +client.login('your token here'); +``` + +The results are the same as the URL examples: + +![Image showing result](/static/attachment-example1.png) + +But what if you have a buffer from an image? Or a text document? Well, it's the same as sending a local file or a URL! + +In the following example, we'll be getting the buffer from a `memes.txt` file, and send it in the message channel. +You can use any buffer you want, and send it. Just make sure to overwrite the filename if it isn't an image! + +```js +// Extract the required classes from the discord.js module +const { Client, Attachment } = require('discord.js'); + +// Import the native fs module +const fs = require('fs'); + +// Create an instance of a Discord client +const client = new Client(); + +/** + * The ready event is vital, it means that only _after_ this will your bot start reacting to information + * received from Discord + */ +client.on('ready', () => { + console.log('I am ready!'); +}); + +client.on('message', message => { + // If the message is '!memes' + if (message.content === '!memes') { + // Get the buffer from the 'memes.txt', assuming that the file exists + const buffer = fs.readFileSync('./memes.txt'); + + /** + * Create the attachment using Attachment, + * overwritting the default file name to 'memes.txt' + * Read more about it over at + * http://discord.js.org/#/docs/main/stable/class/Attachment + */ + const attachment = new Attachment(buffer, 'memes.txt'); + // Send the attachment in the message channel with a content + message.channel.send(`${message.author}, here are your memes!`, attachment); + } +}); + +// Log our bot in using the token from https://discordapp.com/developers/applications/me +client.login('your token here'); +``` + +And of course, the results are: + +![Attachment File example 3](/static/attachment-example3.png) diff --git a/docs/examples/avatars.js b/docs/examples/avatars.js index c95337705..c77020efd 100644 --- a/docs/examples/avatars.js +++ b/docs/examples/avatars.js @@ -1,6 +1,6 @@ -/* - Send a user a link to their avatar -*/ +/** + * Send a user a link to their avatar + */ // Import the discord.js module const Discord = require('discord.js'); @@ -8,11 +8,10 @@ const Discord = require('discord.js'); // Create an instance of a Discord client const client = new Discord.Client(); -// The token of your bot - https://discordapp.com/developers/applications/me -const token = 'your bot token here'; - -// The ready event is vital, it means that your bot will only start reacting to information -// from Discord _after_ ready is emitted +/** + * The ready event is vital, it means that only _after_ this will your bot start reacting to information + * received from Discord + */ client.on('ready', () => { console.log('I am ready!'); }); @@ -26,5 +25,5 @@ client.on('message', message => { } }); -// Log our bot in -client.login(token); +// Log our bot in using the token from https://discordapp.com/developers/applications/me +client.login('your token here'); diff --git a/docs/examples/embed.js b/docs/examples/embed.js new file mode 100644 index 000000000..66e0fcf10 --- /dev/null +++ b/docs/examples/embed.js @@ -0,0 +1,38 @@ +/** + * An example of how you can send embeds + */ + +// Extract the required classes from the discord.js module +const { Client, RichEmbed } = require('discord.js'); + +// Create an instance of a Discord client +const client = new Client(); + +/** + * The ready event is vital, it means that only _after_ this will your bot start reacting to information + * received from Discord + */ +client.on('ready', () => { + console.log('I am ready!'); +}); + +client.on('message', message => { + // If the message is "how to embed" + if (message.content === 'how to embed') { + // We can create embeds using the MessageEmbed constructor + // Read more about all that you can do with the constructor + // over at https://discord.js.org/#/docs/main/stable/class/RichEmbed + const embed = new RichEmbed() + // Set the title of the field + .setTitle('A slick little embed') + // Set the color of the embed + .setColor(0xFF0000) + // Set the main content of the embed + .setDescription('Hello, this is a slick embed!'); + // Send the embed to the same channel as the message + message.channel.send(embed); + } +}); + +// Log our bot in using the token from https://discordapp.com/developers/applications/me +client.login('your token here'); diff --git a/docs/examples/greeting.js b/docs/examples/greeting.js index 55bf2d00d..142889227 100644 --- a/docs/examples/greeting.js +++ b/docs/examples/greeting.js @@ -1,6 +1,6 @@ -/* - A bot that welcomes new guild members when they join -*/ +/** + * A bot that welcomes new guild members when they join + */ // Import the discord.js module const Discord = require('discord.js'); @@ -8,11 +8,10 @@ const Discord = require('discord.js'); // Create an instance of a Discord client const client = new Discord.Client(); -// The token of your bot - https://discordapp.com/developers/applications/me -const token = 'your bot token here'; - -// The ready event is vital, it means that your bot will only start reacting to information -// from Discord _after_ ready is emitted +/** + * The ready event is vital, it means that only _after_ this will your bot start reacting to information + * received from Discord + */ client.on('ready', () => { console.log('I am ready!'); }); @@ -27,5 +26,5 @@ client.on('guildMemberAdd', member => { channel.send(`Welcome to the server, ${member}`); }); -// Log our bot in -client.login(token); +// Log our bot in using the token from https://discordapp.com/developers/applications/me +client.login('your token here'); diff --git a/docs/examples/moderation.md b/docs/examples/moderation.md new file mode 100644 index 000000000..959f404a1 --- /dev/null +++ b/docs/examples/moderation.md @@ -0,0 +1,145 @@ +# Moderation + +In here, you'll see some basic examples for kicking and banning a member. + +## Kicking a member + +Let's say you have a member that you'd like to kick. Here is an example of how you *can* do it. + +```js +// Import the discord.js module +const Discord = require('discord.js'); + +// Create an instance of a Discord client +const client = new Discord.Client(); + +/** + * The ready event is vital, it means that only _after_ this will your bot start reacting to information + * received from Discord + */ +client.on('ready', () => { + console.log('I am ready!'); +}); + +client.on('message', message => { + // Ignore messages that aren't from a guild + if (!message.guild) return; + + // If the message content starts with "!kick" + if (message.content.startsWith('!kick')) { + // Assuming we mention someone in the message, this will return the user + // Read more about mentions over at https://discord.js.org/#/docs/main/stable/class/MessageMentions + const user = message.mentions.users.first(); + // If we have a user mentioned + if (user) { + // Now we get the member from the user + const member = message.guild.member(user); + // If the member is in the guild + if (member) { + /** + * Kick the member + * Make sure you run this on a member, not a user! + * There are big differences between a user and a member + */ + member.kick('Optional reason that will display in the audit logs').then(() => { + // We let the message author know we were able to kick the person + message.reply(`Successfully kicked ${user.tag}`); + }).catch(err => { + // An error happened + // This is generally due to the bot not being able to kick the member, + // either due to missing permissions or role hierarchy + message.reply('I was unable to kick the member'); + // Log the error + console.error(err); + }); + } else { + // The mentioned user isn't in this guild + message.reply('That user isn\'t in this guild!'); + } + // Otherwise, if no user was mentioned + } else { + message.reply('You didn\'t mention the user to kick!'); + } + } +}); + +// Log our bot in using the token from https://discordapp.com/developers/applications/me +client.login('your token here'); +``` + +And the result is: + +![Image showing the result](/static/kick-example.png) + +## Banning a member + +Banning works the same way as kicking, but it has slightly more options that can be changed. + +```js +// Import the discord.js module +const Discord = require('discord.js'); + +// Create an instance of a Discord client +const client = new Discord.Client(); + +/** + * The ready event is vital, it means that only _after_ this will your bot start reacting to information + * received from Discord + */ +client.on('ready', () => { + console.log('I am ready!'); +}); + +client.on('message', message => { + // Ignore messages that aren't from a guild + if (!message.guild) return; + + // if the message content starts with "!ban" + if (message.content.startsWith('!ban')) { + // Assuming we mention someone in the message, this will return the user + // Read more about mentions over at https://discord.js.org/#/docs/main/stable/class/MessageMentions + const user = message.mentions.users.first(); + // If we have a user mentioned + if (user) { + // Now we get the member from the user + const member = message.guild.member(user); + // If the member is in the guild + if (member) { + /** + * Ban the member + * Make sure you run this on a member, not a user! + * There are big differences between a user and a member + * Read more about what ban options there are over at + * https://discord.js.org/#/docs/main/stable/class/GuildMember?scrollTo=ban + */ + member.ban({ + reason: 'They were bad!', + }).then(() => { + // We let the message author know we were able to ban the person + message.reply(`Successfully banned ${user.tag}`); + }).catch(err => { + // An error happened + // This is generally due to the bot not being able to ban the member, + // either due to missing permissions or role hierarchy + message.reply('I was unable to ban the member'); + // Log the error + console.error(err); + }); + } else { + // The mentioned user isn't in this guild + message.reply('That user isn\'t in this guild!'); + } + } else { + // Otherwise, if no user was mentioned + message.reply('You didn\'t mention the user to ban!'); + } + } +}); + +// Log our bot in using the token from https://discordapp.com/developers/applications/me +client.login('your token here'); +``` + +And the result is: + +![Image showing the result](/static/ban-example.png) diff --git a/docs/examples/ping.js b/docs/examples/ping.js index 541038bd5..1b14332de 100644 --- a/docs/examples/ping.js +++ b/docs/examples/ping.js @@ -1,6 +1,6 @@ -/* - A ping pong bot, whenever you send "ping", it replies "pong". -*/ +/** + * A ping pong bot, whenever you send "ping", it replies "pong". + */ // Import the discord.js module const Discord = require('discord.js'); @@ -8,11 +8,10 @@ const Discord = require('discord.js'); // Create an instance of a Discord client const client = new Discord.Client(); -// The token of your bot - https://discordapp.com/developers/applications/me -const token = 'your bot token here'; - -// The ready event is vital, it means that your bot will only start reacting to information -// from Discord _after_ ready is emitted +/** + * The ready event is vital, it means that only _after_ this will your bot start reacting to information + * received from Discord + */ client.on('ready', () => { console.log('I am ready!'); }); @@ -26,5 +25,5 @@ client.on('message', message => { } }); -// Log our bot in -client.login(token); +// Log our bot in using the token from https://discordapp.com/developers/applications/me +client.login('your token here'); diff --git a/docs/examples/webhook.js b/docs/examples/webhook.js index fd8a567d1..77f58c448 100644 --- a/docs/examples/webhook.js +++ b/docs/examples/webhook.js @@ -1,6 +1,6 @@ -/* - Send a message using a webhook -*/ +/** + * Send a message using a webhook + */ // Import the discord.js module const Discord = require('discord.js'); diff --git a/docs/general/faq.md b/docs/general/faq.md index d7e4188b8..2bbb90bfb 100644 --- a/docs/general/faq.md +++ b/docs/general/faq.md @@ -12,10 +12,10 @@ Update to Node.js 6.0.0 or newer. node-opus is greatly preferred, due to it having significantly better performance. ## How do I install FFMPEG? -- **npm:** `npm install --save ffmpeg-binaries` +- **npm:** `npm install ffmpeg-binaries` - **Ubuntu 16.04:** `sudo apt install ffmpeg` - **Ubuntu 14.04:** `sudo apt-get install libav-tools` -- **Windows:** See the [FFMPEG section of AoDude's guide](https://github.com/bdistin/OhGodMusicBot/blob/master/README.md#download-ffmpeg). +- **Windows:** `npm install ffmpeg-binaries` or see the [FFMPEG section of AoDude's guide](https://github.com/bdistin/OhGodMusicBot/blob/master/README.md#download-ffmpeg). ## How do I set up node-opus? - **Ubuntu:** Simply run `npm install node-opus`, and it's done. Congrats! diff --git a/docs/general/welcome.md b/docs/general/welcome.md index 8e7fc74f8..6412975da 100644 --- a/docs/general/welcome.md +++ b/docs/general/welcome.md @@ -10,6 +10,7 @@ NPM downloads Build status Dependencies + Patreon

NPM info diff --git a/docs/index.yml b/docs/index.yml index 9aa9e7948..7c5b3b280 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -18,7 +18,13 @@ path: ping.js - name: Avatars path: avatars.js + - name: Attachments + path: attachments.md - name: Server greeting path: greeting.js + - name: Message Embed + path: embed.js + - name: Moderation + path: moderation.md - name: Webhook path: webhook.js diff --git a/docs/topics/voice.md b/docs/topics/voice.md index dc70eb0e9..9db041aeb 100644 --- a/docs/topics/voice.md +++ b/docs/topics/voice.md @@ -4,12 +4,16 @@ Voice in discord.js can be used for many things, such as music bots, recording o In discord.js, you can use voice by connecting to a `VoiceChannel` to obtain a `VoiceConnection`, where you can start streaming and receiving audio. To get started, make sure you have: -* ffmpeg - `npm install ffmpeg-binaries` +* FFmpeg - `npm install ffmpeg-binaries` * an opus encoder, choose one from below: * `npm install opusscript` * `npm install node-opus` * a good network connection +The preferred opus engine is node-opus, as it performs significantly better than opusscript. When both are available, discord.js will automatically choose node-opus. +Using opusscript is only recommended for development environments where node-opus is tough to get working. +For production bots, using node-opus should be considered a necessity, especially if they're going to be running on multiple servers. + ## Joining a voice channel The example below reacts to a message and joins the sender's voice channel, catching any errors. This is important as it allows us to obtain a `VoiceConnection` that we can start to stream audio with.