1. How To Use

Here we will be talking about how to use the interface of the QalibContext

Simple Usage

This is a simple XML file that contains a barebones embed

<discord>
    <embed key="test_key">
        <title>Hello World</title>
        <colour>cyan</colour>
        <fields>
            <field>
                <name>Field 1</name>
                <value>This is the first field in the embed that is mandatory</value>
            </field>
        </fields>
    </embed>
</discord>

Lets dissect this, piece by piece. First off, we have the <discord> tag which is the container (ElementTree) for all the <embed> elements. We can have a variable number of <embed> elements and they are uniquely identified by their key attribute such as <embed key="test_key">, which is used to identify this embed, in this case test_key uniquely identifies this embed.

We then use the the components of the embed class, so the 3 mandatory elements of an embed that is required to render it is the <title>, <colour>/<color>, and at least one <field> in the <fields> container, which contain a <name>, and a <value>.

Using more of the attributes that can associated with an embed

Each embed can be extended to leverage more the things that an embed can offer such as:

1. Description
2. Type
3. Timestamp (with format attribute defaulting to "%Y-%m-%d %H:%M:%S.%f")
4. Url
5. Footer
1. Text
2. Icon
6. Thumbnail
7. Image
8. Author
1. Name
2. Icon
3. Url

So an example of fully using all the features an embed could offer is as such:

<discord>
    <embed key="test_key">
        <title>Test</title>
        <description>Test Description</description>
        <type>rich</type>
        <colour>magenta</colour>
        <timestamp format="%d-%m%-Y">22-04-2023</timestamp>
        <url>https://www.discord.com</url>
        <fields>
            <field>
                <name>Test Field</name>
                <text>Test Text</text>
            </field>
        </fields>
        <footer>
            <text>Test Footer</text>
            <icon>https://cdn.discordapp.com/embed/avatars/0.png</icon>
        </footer>
        <thumbnail>https://cdn.discordapp.com/embed/avatars/0.png</thumbnail>
        <image>https://cdn.discordapp.com/embed/avatars/0.png</image>
        <author>
            <name>Test Author</name>
            <icon>https://cdn.discordapp.com/embed/avatars/0.png</icon>
            <url>https://discordapp.com</url>
        </author>
    </embed>
</discord>

Rendering Values

If you are using the EmbedManager as a wrapper (QalibContext with a EmbedProxy) over the default context, then any value within braces {} will be treated as an object (will apply .format()). If you are using the JinjaManager then anything within a double braces {{ }} will be evaluated as well as all the features that Jinja utilises such as for loops. Simple example of this with the EmbedManager (so {} for formatting) will be

<discord>
    <embed key="bank">
        <title>Balance {player.name}</title>
        <colour>cyan</colour>
        <fields>
            <field>
                <name>{player.bank_name}</name>
                <value>Has 💵{player.funds} EGP in the bank</value>
            </field>
        </fields>
    </embed>
</discord>

Embed Manager

so if we have this sample file called player.xml that is in the templates/ directory:

<discord>
    <embed key="army">
        <title>Army of {player.name}</title>
        <colour>cyan</colour>
        <fields>
            <field>
                <name>{player.army_name}</name>
                <value>Has 💂{player.soldiers} defending the nation</value>
            </field>
        </fields>
    </embed>
    <embed key="bank">
        <title>Hello {player.name}</title>
        <colour>cyan</colour>
        <fields>
            <field>
                <name>{player.bank_name}</name>
                <value>Has 💵{player.funds} EGP in the bank</value>
            </field>
        </fields>
    </embed>
</discord>

and then can be used by an EmbedManager instance

from dataclasses import dataclass

import discord
from discord.ext import commands

import qalib

bot = commands.AutoShardedBot(command_prefix="!", intents=discord.Intents.all())

@dataclass
class Player:
    name: str
    bank: str
    funds: float
    army_name: str
    soldiers: int
    
def fetch_player(name: str) -> Player:
    ...

@bot.command()
@qalib.embed_manager("templates/test.xml")
async def test(ctx):
    await ctx.rendered_send("test_key", keywords={
        "player": fetch_player(name)
    })