2. XML Rendering

This is the main way to use 🃏 Qalib. You must have a <discord> tag that spans the entire document, as it is treated as the root of the ElementTree.

You can then have multiple embeds which are each contained in a <embed> tag, and must have a key attribute that uniquely identifies them among the other embed keys, and is written as <embed key="key_name">.

To render values dynamically, simply put them in between braces, and the renderer will format it when you use the context's rendered_send() method, as seen in the next section.

It is safe to skip any non-mandatory fields that an embed would not require, they will simply use their default values.

🧩 Sample

<discord>
    <embed key="test_key">
        <title>Test Title</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>{author_name}</name>
            <icon>https://cdn.discordapp.com/embed/avatars/0.png</icon>
            <url>https://discordapp.com</url>
        </author>
    </embed>
    <embed key="test_key2">
        <title>Test</title>
        <colour>magenta</colour>
        <fields>
            <field>
                <name>Test Field</name>
                <text>Test Text</text>
            </field>
        </fields>
    </embed>
</discord>

For the purpose of this example, we store this file in templates/test.xml

⚡ Using EmbedManager

import discord
from discord.ext import commands

import qalib
from qalib.template_engines.formatter import Formatter

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

@bot.command()
@qalib.qalib_context(Formatter(), "templates/test.xml")
async def test(ctx, name: str):
    await ctx.rendered_send("test_key", keywords={
        "author_name": str
    })

🖌️ Views

The main components are rendered and instantiate the mapped component/item in discord.py. The limit to the number of components/items that you can use in one embed is capped at 25.

For each example we will write how the component should look like. Components/Items should be written in the view section, where the comment is.

<discord>
    <embed key="test">
        <title>This is a Test!</title>
        <colour>cyan</colour>
        <fields>
            <field>
                <name>Test Field</name>
                <value>Test Value</value>
            </field>
        </fields>
        <view>
            <!--Each component/item should go here-->
        </view>
    </embed>
</discord>

🆗 Button

Rendering a Button in .xml.

<button key="click_key">
    <label>Click Me!</label>
    <style>success</style>
    <custom_id>{custom_id}</style>
    <disabled>false</disabled>
    <url>https://github.com/YousefEZ/discord-qalib</url>
    <emoji>
        <name>joy</name>
    </emoji>
</button>

🏴 Select

Rendering a Select in .xml

<select key="select_key">
    <placeholder>Select An Option</placeholder>
    <custom_id>{custom_id}</custom_id>
    <min_values>1</min_values>
    <max_values>3</max_values>
    <disabled>false</disabled>
    <options>
        <option>
            <label>Amman</label>
            <value>0</value>
            <description>The Capital of Jordan</description>
            <emoji>
                <name>Petra</name>
                <id>217348923789</id>
                <animated>false</false>
            </emoji>
        </option>
        <option>
            <label>Baghdad</label>
        </option>
        <option>
            <label>Cairo</label>
        </option>
        <option>
            <label>Damascus</label>
        </option>
    </options>
</select>

📣 Channel Select

Rendering a Channel Select in .xml

<channel_select key="channel_select_key">
    <placeholder>Select a Channel</channel_type>
    <channel_types>
        <channel_type>text</channel_type>
        <channel_type>voice</channel_type>
    </channel_types>
    <min_values>1</min_values>
    <max_values>5</max_values>
    <disabled>false</disabled>
</channel_select>

🏷️ Mentionable Select

Rendering a Mentionable Select in .xml

<mentionable_select key="mentionable_key">
    <placeholder>Select Something to Mention</placeholder>
    <min_values>1</min_values>
    <max_values>2</max_values>
    <disabled>false</disabled>
</mentionable_select>

🥷 User Select

Rendering a User Select in .xml

<user_select key="user_key">
    <placeholder>Select a User</placeholder>
    <min_values>1</min_values>
    <max_values>2</max_values>
    <disabled>false</disabled>
</user_select>

🎭 Role Select

Rendering a Role Select in .xml

<role_select key="role_select_key">
    <placeholder>Select a Role</placeholder>
    <min_values>1</min_values>
    <max_values>2</max_values>
    <disabled>false</disabled>
</role_select>

💬 Text Input

Rendering a Text Input in .xml

<text_input key="text_input_key">
    <label>What do you think?</label>
    <style>short</style>
    <placeholder>Write your response...</placeholder>
    <default>N/A</default>
    <min_length>0</min_length>
    <max_length>150<max_length>
</text_input>