Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Refactor from More Features to Embeds, Events, Markdown #236

Open
wants to merge 20 commits into
base: main
Choose a base branch
from
Open

Refactor from More Features to Embeds, Events, Markdown #236

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
9356cc8
Refactor from More Features to Embeds, Events, Markdown
Elitesparkle Oct 16, 2022
864c32f
Fix end of files
Elitesparkle Oct 16, 2022
c300cff
New category + md examples
BobDotCom Oct 17, 2022
9d6a9f8
Merge branch 'main' into more-features
BobDotCom Oct 17, 2022
7490f69
Fix syntax highlight, sections, examples, and some sentences
Elitesparkle Oct 17, 2022
235cfee
Merge branch 'main' into more-features
Elitesparkle Oct 17, 2022
0ffb222
Merge branch 'main' into more-features
Elitesparkle Oct 17, 2022
53e726d
Fix internal link
Elitesparkle Oct 19, 2022
db48c64
Fix examples
Elitesparkle Oct 19, 2022
40031e0
Refactor indentation
Elitesparkle Oct 19, 2022
c783550
Merge branch 'main' into more-features
Elitesparkle Oct 19, 2022
9e2b07b
Fix multi-line quote example
Elitesparkle Oct 19, 2022
11b0903
Merge branch 'more-features' of https://github.com/Elitesparkle/guide…
Elitesparkle Oct 19, 2022
f267fd6
Revert "Fix examples"
Elitesparkle Oct 19, 2022
0627433
Fix examples
Elitesparkle Oct 20, 2022
b1182ef
Fix titles and multi-line quote example
Elitesparkle Oct 20, 2022
3f3d143
Remove non-working language names from code block examples
Elitesparkle Oct 20, 2022
ccd56bd
Update docs/getting-started/styling-messages/markdown.mdx
BobDotCom Oct 20, 2022
fae2951
Update docs/getting-started/styling-messages/markdown.mdx
BobDotCom Oct 20, 2022
884561d
Update docs/getting-started/styling-messages/markdown.mdx
BobDotCom Oct 20, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 56 additions & 0 deletions docs/getting-started/events.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
title: Events
description: Events used to listen for certain actions and react to them.
---

# Events

## Event Handlers

Events in Discord are a way to listen for certain actions. For example, if you want to know when a user joins your server so you could send a welcome message, you can use the `on_member_join` event.

First, you need to ask Discord to send you events. This is done via "Intents". Read up the [Intents](../Popular-Topics/intents) page for more information.

Once you understand what intents are, you can enable the events you need, or just use the default ones with `discord.Intents.all()`.

Now that that's done, let's add an event handler for when a user joins the server. We will use the [`on_member_join` event](https://docs.pycord.dev/en/master/api.html#discord.on_member_join). We will send a private message to the user welcoming them to the server.

```python
@bot.event
async def on_member_join(member):
await member.send(
f'Welcome to the server, {member.mention}! Enjoy your stay here.'
)
```

We use the [`discord.Bot.event` decorator](https://docs.pycord.dev/en/master/api.html#discord.Bot.event) to add the event handler.

The `on_member_join` event is called when a user joins the server. The `member` parameter is the user that joined. Different events have different names and parameters. You can find all of them [here](https://docs.pycord.dev/en/master/api.html#discord.Intents).

So, that's how you add event handlers!

## Waiting for User Response

Let's say you want to create a Guess-the-Number game (where the user has to guess a number between 1-10). You need to send a message to a user and wait for them to respond. You can do this with the [`wait_for`](https://docs.pycord.dev/en/master/api.html#discord.Bot.wait_for) method.

```python
@bot.command()
async def gtn(ctx):
"""A Slash Command to play a Guess-the-Number game."""

await ctx.respond('Guess a number between 1 and 10.')
guess = await bot.wait_for('message', check=lambda message: message.author == ctx.author)

if int(guess.content) == 5:
await ctx.send('You guessed it!')
else:
await ctx.send('Nope, try again.')
```

`wait_for` takes one argument, which is the event type. The event type is the name of the event you want to wait for. In this case, it's `message`. It could also be `reaction` to wait for a reaction to be added.

We pass a keyword argument to `wait_for` called `check`. The function may look complicated if you're a beginner. We pass a `lambda` function, which simplifies the code a bit.

The lambda function takes one parameter, `message`. When Pycord receives a message, it passes it to the `check` function. If the function returns `True`, the message is returned. If the function returns `False`, the message is ignored and the bot waits for another message.

Here, we check if the message is from the user that sent the command. We simply use `message.author == ctx.author`. This will check if the author of the message was the person who invoked the command.
6 changes: 6 additions & 0 deletions docs/getting-started/styling-messages/_category_.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"label": "Styling Messages",
"link": {
"type": "generated-index"
}
}
219 changes: 10 additions & 209 deletions docs/getting-started/more-features.mdx → ...tting-started/styling-messages/embeds.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: More Features
description: More features to make your bot cool and snazzy.
title: Embeds
description: Discord components used to present data with special formatting and structure.
---

import {
Expand All @@ -13,65 +13,10 @@ import {
} from "discord-message-components/packages/react";
import "discord-message-components/packages/react/dist/style.css";

import DiscordComponent from "../../src/components/DiscordComponent";
import DiscordComponent from "../../../src/components/DiscordComponent";

So, you just created your first Pycord bot! Now, let's add some more features to it. This will include adding event handlers, waiting for user response, styling the messages, and more.
# Embeds

## Events

### Event Handlers

Events in Discord are a way to listen for certain actions. For example, if you want to know when a user joins your server so you could send a welcome message, you can use the `on_member_join` event.

First, you need to ask Discord to send you events. This is done via "Intents". Read up the [Intents](../Popular-Topics/intents) page for more information.

Once you understand what intents are, you can enable the events you need, or just use the default ones with `discord.Intents.all()`.

Now that that's done, let's add an event handler for when a user joins the server. We will use the [`on_member_join` event](https://docs.pycord.dev/en/master/api.html#discord.on_member_join). We will send a private message to the user welcoming them to the server.

```python
@bot.event
async def on_member_join(member):
await member.send(
f'Welcome to the server, {member.mention}! Enjoy your stay here.'
)
```

We use the [`discord.Bot.event` decorator](https://docs.pycord.dev/en/master/api.html#discord.Bot.event) to add the event handler.

The `on_member_join` event is called when a user joins the server. The `member` parameter is the user that joined. Different events have different names and parameters. You can find all of them [here](https://docs.pycord.dev/en/master/api.html#discord.Intents).

So, that's how you add event handlers!

### Waiting for User Response

Let's say you want to create a Guess-the-Number game (where the user has to guess a number between 1-10). You need to send a message to a user and wait for them to respond. You can do this with the [`wait_for`](https://docs.pycord.dev/en/master/api.html#discord.Bot.wait_for) method.

```python
@bot.command()
async def gtn(ctx):
"""A Slash Command to play a Guess-the-Number game."""

await ctx.respond('Guess a number between 1 and 10.')
guess = await bot.wait_for('message', check=lambda message: message.author == ctx.author)

if int(guess.content) == 5:
await ctx.send('You guessed it!')
else:
await ctx.send('Nope, try again.')
```

`wait_for` takes one argument, which is the event type. The event type is the name of the event you want to wait for. In this case, it's `message`. It could also be `reaction` to wait for a reaction to be added.

We pass a keyword argument to `wait_for` called `check`. The function may look complicated if you're a beginner. We pass a `lambda` function, which simplifies the code a bit.

The lambda function takes one parameter, `message`. When Pycord receives a message, it passes it to the `check` function. If the function returns `True`, the message is returned. If the function returns `False`, the message is ignored and the bot waits for another message.

Here, we check if the message is from the user that sent the command. We simply use `message.author == ctx.author`. This will check if the author of the message was the person who invoked the command.

## Styling Messages

### Embeds
Embeds are a Discord feature that allows applications to format their messages in cool embedded format,
enabling your bot to lay out messages with a lot of text into neat fields.

Expand Down Expand Up @@ -176,7 +121,7 @@ bot.run("TOKEN")

<br/>

This simple command sends replies to a [slash command](../interactions/application-commands/slash-commands) with an embed.
This simple command sends replies to a [slash command](../../interactions/application-commands/slash-commands) with an embed.
Let's break it down:

```py
Expand All @@ -201,9 +146,9 @@ embed.add_field(title="Inline Field 2", value="Inline Field 2", inline=True)
embed.add_field(title="Inline Field 3", value="Inline Field 3", inline=True)
```

This small section shows off embed fields. You can add fields to embeds with the [`add_field` method](https://docs.pycord.dev/en/master/api.html#discord.Embed.add_field)
This small section shows off embed fields. You can add up to 25 fields to embeds with the [`add_field` method](https://docs.pycord.dev/en/master/api.html#discord.Embed.add_field)
of the [`discord.Embed`](https://docs.pycord.dev/en/master/api.html#embed) class. These consist of three
keyword arguments: `title`, `value`, and `inline`. `title` and `value` are both required arguments, which inline defaults to `False` if it's not defined. The `inline` argument specifies whether or not space will be divided among the inline fields. There could be a mix of fields where inline has different values too.
keyword arguments: `title`, `value`, and `inline`. `title` and `value` are both required arguments, whereas `inline` is optional and defaults to `False` when not defined. The `inline` argument specifies whether or not space will be divided among the inline fields. There could be a mix of fields where inline has different values too.

```py
embed.set_footer(text="Footer! No markdown here.") # footers can have icons too
Expand All @@ -224,153 +169,9 @@ method, you can set a small image to reside at the top-right of the embed. This
method, you can set an image to sit at the bottom of an embed. This has a single `url` kwarg.

There are a lot more methods and attributes you can use to configure embeds. Here, we just covered the basics. Also, remember that all of these values are not necessary in an embed. An embed may only contain a few of these. For example, only a description, a title and a description, and so on.

### Markdown
Markdown is a type of markup language that's limited in terms of formatting yet simple. Discord allows
for a watered-down version of markdown to be in their messages.

#### Text Markdown

Text formatting can be used in messages and in most embed parts,
as explained in the dedicated section below.

<table>
<tr>
<td>*italics*</td>
<td>__*underlined italics*__</td>
</tr>
<tr>
<td>**bold**</td>
<td>__**underlined bold**__</td>

</tr>
<tr>
<td>***bold italics***</td>
<td>__***underlined bold italics***__</td>

</tr>
<tr>
<td>__underlined__</td>
<td>~~strikethrough~~</td>
</tr>
</table>

#### Code Markdown

To create a single-line code block without syntax highlight, wrap the text between single backticks.
This code block will only add a dark background to the text.
:::info Related Topics

```
`print("Hello world!")`
```

To create a multi-line code block without syntax highlight, wrap the text between triple backticks
on first and last line. This type of code block will encase the code inside a box.

````
```
message = "Hello world!"
print(message)
```
````

To create a multi-line block with syntax highlight, add the name of the language you are using right after
the triple backticks on the first line. For example, for Python you can write either "python" or "py".

````
```python
message = "Hello world!"
print(message)
```
````

If you want to use syntax highlight for a single line of code, you still have to format it
like a multi-line block but the code must be on a separate line than the triple backticks.

#### Quote Markdown

To create a single-line quote block, start the line with `>` followed by a space.

```
> This is a single-line quote.
```

To create a multi-line quote block, write `>>>` followed by a space. All text
from that point onwards will be included in that quote block.

```
>>> This is a
multi-line quote.
```

#### Spoiler Markdown

To hide a spoiler, encase the text between double pipes. The users
will have to click on it before being able to see the text contained in it.

```
||spoiler||
```

#### Link Markdown

Link formatting only works in embeds and messages sent through webhooks,
by using the following syntax:

```
[Pycord](https://pycord.dev/)
```

Inside the supported elements that have just been mentioned,
the example above will look like this: [`Pycord`](https://pycord.dev/)

Outside of them, the link will still be clickable but the formatting will be ignored,
therefore the example above will look similarly to this: `[Pycord](https://pycord.dev/)`

#### Embed Markdown

Adding markdown to your embeds or messages will give your bot the sparkle it needs,
however, markdown is limited inside embeds. Use the following table as a reference
and keep in mind that embed title and filed names will always show in **bold**.
- [Markdown](markdown)

<table>
<thead>
<tr>
<th>Part</th>
<th>Text</th>
<th>Link</th>
</tr>
</thead>
<tbody>
<tr>
<td>Embed Author</td>
<td>No</td>
<td>No</td>
</tr>
<tr>
<td>Embed Title</td>
<td>Yes</td>
<td>No</td>
</tr>
<tr>
<td>Embed Description</td>
<td>Yes</td>
<td>Yes</td>
</tr>
<tr>
<td>Field Name</td>
<td>Yes</td>
<td>No</td>
</tr>
<tr>
<td>Field Value</td>
<td>Yes</td>
<td>Yes</td>
</tr>
<tr>
<td>Embed Footer</td>
<td>No</td>
<td>No</td>
</tr>
</tbody>
</table>
:::
Loading