-
Notifications
You must be signed in to change notification settings - Fork 1
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 messages with the <message> tag, and must have a key attribute that uniquely identifies them among the other embed keys, and is written as <message 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.
<discord>
<message key="test_key">
<embed>
<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>
</message>
<message key="test_key2">
<embed>
<title>Test</title>
<colour>magenta</colour>
<fields>
<field>
<name>Test Field</name>
<text>Test Text</text>
</field>
</fields>
</embed>
</message>
</discord>For the purpose of this example, we store this file in templates/test.xml
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>
<components>
<!--Each component/item should go here-->
</components>
</view>
</embed>
</discord>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>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>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>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>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>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>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 can 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>Menus can be rendered by using the <menu> tag with a key identifier such as <menu key="test">, following messages or page references <page key="other_test"> that refer to messages outside of the menu tag
<discord>
<message key="test1">
<content>This is a test</content>
</message>
<menu key="test2">
<pages>
<page key="test1"/>
<message>
<content>This is the second page</content>
<message>
</pages>
</menu>
</discord>these are messages that expand to another message if the main embed's field overrun the character limit, forming a menu. This is compatible with menus.
<discord>
<expansive key="test_key3">
<timeout/>
<embed>
<title>Title</title>
<colour>teal</colour>
<expansive_field>
<name>hello planet</name>
<value>in iaculis nunc sed augue lacus viverra vitae congue eu consequat ac felis donec et
odio pellentesque diam volutpat commodo sed egestas egestas fringilla phasellus
faucibus scelerisque eleifend donec pretium vulputate sapien nec sagittis
aliquam malesuada bibendum arcu vitae elementum curabitur vitae nunc sed velit
dignissim sodales ut eu sem integer vitae justo eget magna fermentum iaculis eu
non diam phasellus vestibulum lorem sed risus ultricies tristique nulla aliquet enim tortor
at auctor urna nunc id cursus metus aliquam eleifend mi in nulla
posuere sollicitudin aliquam ultrices sagittis orci a scelerisque purus semper eget
duis at tellus at urna condimentum
in iaculis nunc sed augue lacus viverra vitae congue eu consequat ac felis donec et
odio pellentesque diam volutpat commodo sed egestas egestas fringilla phasellus
faucibus scelerisque eleifend donec pretium vulputate sapien nec sagittis
aliquam malesuada bibendum arcu vitae elementum curabitur vitae nunc sed velit
dignissim sodales ut eu sem integer vitae justo eget magna fermentum iaculis eu
non diam phasellus vestibulum lorem sed risus ultricies tristique nulla aliquet enim tortor
at auctor urna nunc id cursus metus aliquam eleifend mi in nulla
posuere sollicitudin aliquam ultrices sagittis orci a scelerisque purus semper eget
duis at tellus at urna condimentum</value>
</expansive_field>
</embed>
</expansive>
</discord>This is will expand into two pages as a menu
🃏 Discord-Qalib 2023