XML

Bases: Deserializer[K_contra]

Read and process the data given by the XML file, and use given user objects to render the text

`deserialize(source, key, callables, events)`

This method is used to deserialize the embed from the XML file.

Parameters:

source (str) –

raw string containing the element
key (K) –

key of the element
callables (Dict[str, Callback]) –

dictionary containing the callables to use for the components
events (EventCallbacks) –

dictionary containing the events to use for the components

Returns (Message): message containing the embed and its view

`deserialize_element(document, element, callables, events)`

This method is used to deserialize the embed from the XML file.

Parameters:

document (Element) –

document containing all the elements
element (Element) –

element containing the embed
callables (Dict[str, Callback]) –

dictionary containing the callables to use for the components
events (EventCallbacks) –

dictionary containing the events to use for the components

Returns (ReturnType): all possible deserialized objects.

`deserialize_expansive(element, callbacks, events)`

Deserializes an embed from an XML file, and returns it as a Display object.

Parameters:

element (Element) –

templated document contents to deserialize.
callbacks (Dict[str, Callback]) –

A dictionary containing the callables to use for the components.
events (EventCallbacks) –

A dictionary containing the events to use for the components.

Returns (List[Message]): A list of messages containing the embed and its view.

`deserialize_menu(element, callables, events, *, document)`

Deserializes a menu from an XML file, by generating a list of displays that are connected by buttons in their views to navigate between them.

Parameters:

element (Element) –

The XML Menu Element to deserialize.
callables (Dict[str, Callback]) –

A dictionary containing the callables to use for the components.
events (EventCallbacks) –

A dictionary containing the events to callback on.
document (Element) –

The entire document

Returns (List[Display]): List of displays that are connected by buttons in their views to navigate between them.

`deserialize_menu_arrows(arrows_view)`

Deserializes the arrows of a menu from an XML file, and returns it as a dictionary.

Parameters:

arrows_view (Element) –

templated document contents to deserialize.

Returns (Dict[MenuActions, ButtonComponent]): A dictionary containing the arrows.

`deserialize_message(message_tree, callables, events, **overrides)`

Deserializes an embed from an ElementTree.Element, and returns it as a Display object.

Parameters:

message_tree (Element) –

The element to deserialize the embed from.
callables (Dict[str, Callback]) –

A dictionary containing the callables to use for the components.
events (EventCallbacks) –

A dictionary containing the events to use for the components.
**overrides (Any, default: {} ) –

any overrides to apply to the Message

Returns (Message): A display object containing the embed and its view.

`deserialize_modal(element, callables, events)`

Method to deserialize a modal into a discord.ui.Modal object

Parameters:

element (Element) –

The element to deserialize into a modal
callables (Dict[str, Callback]) –

A dictionary containing the callables to use for the components
events (Dict[ModalEvents, ModalEventsCallbacks]) –

A dictionary containing the events to callback on

Returns (discord.ui.Modal): A discord.ui.Modal object

`get_attribute(element, attribute)` `staticmethod`

Renders an attribute from an ElementTree.Element.

Parameters:

element (Element) –

The element to render the attribute from.
attribute (str) –

The name of the attribute to render.

Returns (str): The value of the attribute.

`get_element_text(element)` `staticmethod`

Renders the given ElementTree.Element by returning its text.

Parameters:

element (Element) –

The element to render.

Returns (str): The rendered element.

`pop_component(component, key)` `staticmethod`

Pops a component from the given element, and returns it.

Parameters:

component (Element) –

The element to pop the component from.
key (str) –

The key of the component to pop.

Returns (Optional[ElementTree.Element]): The popped component, or None if it doesn't exist.

`render_component(component, callback)`

Renders a component based on the tag in the element.

Parameters:

component (Element) –

The component to render, contains all template.
callback (Optional[Callback]) –

The callback to use if the user interacts with this component.

Returns (discord.ui.Item): The rendered component.

`render_components(view, callables)`

Renders a list of components based on the identifier given.

Parameters:

view (View) –

The raw view.
callables (Dict[str, Callback]) –

The callbacks to use if the user interacts with the components.

Returns (Optional[List[discord.ui.Item]]): The rendered components.

Working with XML

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

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

href="#__codelineno-0-1"><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>
🖌️ 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>
    <message key="test">

        <embed>
            <title>This is a Test!</title>
            <colour>cyan</colour>
            <fields>
                <field>
                    <name>Test Field</name>
                    <value>Test Value</value>
                </field>
            </fields>
            <view>
                <components>
                    <!--Each component/item should go here-->
                </components>
            </view>
        </embed>
    </message>
</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>

📝 Modals
Modals can be rendered by using the <modal>. They also need to be passed the methods using their method names as their keys. A Sample document containing Modals can be seen here
<discord>
    <modal key="modal1" title="Questionnaire">
        <text_input>
            <label>What is your name?</label>
            <placeholder>Enter your name</placeholder>
            <style>long</style>
        </text_input>
        <text_input>
            <label>What is your age?</label>
            <placeholder>Enter your age</placeholder>
            <style>long</style>
        </text_input>
    </modal>
</discord>

XML

deserialize(source, key, callables, events)

deserialize_element(document, element, callables, events)

deserialize_expansive(element, callbacks, events)

deserialize_menu(element, callables, events, *, document)

deserialize_menu_arrows(arrows_view)

deserialize_message(message_tree, callables, events, **overrides)

deserialize_modal(element, callables, events)

get_attribute(element, attribute) staticmethod

get_element_text(element) staticmethod

pop_component(component, key) staticmethod

render_component(component, callback)

render_components(view, callables)

Working with XML

🧩 Sample

🖌️ Views

🆗 Button

🏴 Select

📣 Channel Select

🏷️ Mentionable Select

🥷 User Select

🎭 Role Select

💬 Text Input

📝 Modals

`deserialize(source, key, callables, events)`

`deserialize_element(document, element, callables, events)`

`deserialize_expansive(element, callbacks, events)`

`deserialize_menu(element, callables, events, *, document)`

`deserialize_menu_arrows(arrows_view)`

`deserialize_message(message_tree, callables, events, **overrides)`

`deserialize_modal(element, callables, events)`

`get_attribute(element, attribute)` `staticmethod`

`get_element_text(element)` `staticmethod`

`pop_component(component, key)` `staticmethod`

`render_component(component, callback)`

`render_components(view, callables)`