diff --git a/docs/docs/expressions.md b/docs/docs/expressions.md index 6cfda64..0f490cd 100644 --- a/docs/docs/expressions.md +++ b/docs/docs/expressions.md @@ -40,6 +40,77 @@ Get the URL of the user's avatar decoration URL. This will return none if the us %user%'[s] [user] (decoration[s] avatar|avatar decoration[s]) ``` +## User's Equipped Server Tag + +[[[ macros.required_version('4.27.0') ]]] +[[[ macros.return_type('rolecountobject') ]]] + +Get the server tag that a user has equipped (also called "primary guild tag"). This represents the tag that the user has chosen to display on their profile for a specific server. + +Server tags are a Discord feature that allows users to choose a tag representing their identity or role in a server. The equipped tag is the one displayed prominently on their profile. + +=== "Examples" + + ```applescript + set {_tag} to user tag of event-user + set {_primaryTag} to user primary guild tag of {_member} + + # Example: Display user's equipped tag + discord command mytag: + prefixes: ! + trigger: + set {_tag} to user tag of event-user + if {_tag} is set: + reply with "Your equipped server tag: %discord name of {_tag}%" + else: + reply with "You don't have an equipped server tag." + ``` + +=== "Patterns" + + ```applescript + [the] [user] [primary] [guild] tag of %user% + %user%'[s] [user] [primary] [guild] tag + ``` + +## User's Server Tag Icon + +[[[ macros.required_version('4.27.0') ]]] +[[[ macros.return_type('string') ]]] + +Get the icon URL of a user's equipped server tag. Returns none if the user doesn't have an equipped tag or if the tag has no icon. + +=== "Examples" + + ```applescript + set {_icon} to user tag icon of event-user + set {_iconUrl} to user primary guild tag icon url of {_member} + + # Example: Show tag with icon in embed + discord command profile []: + prefixes: ! + trigger: + set {_user} to arg-1 ? event-user + set {_tag} to user tag of {_user} + set {_icon} to user tag icon url of {_user} + + make embed: + set title of embed to "%discord name of {_user}%'s Profile" + if {_tag} is set: + set description of embed to "Equipped Tag: %discord name of {_tag}%" + set thumbnail of embed to {_icon} if {_icon} is set + else: + set description of embed to "No equipped server tag" + reply with last embed + ``` + +=== "Patterns" + + ```applescript + [the] [user] [primary] [guild] tag icon [url] of %user% + %user%'[s] [user] [primary] [guild] tag icon [url] + ``` + ## Discord Command Argument [[[ macros.required_version('4.0.0') ]]] @@ -1033,6 +1104,63 @@ Get the parent channel of a thread channel. It can return a text, news or forum %guildchannel%'[s] thread parent [channel] ``` +## Thread Owner + +[[[ macros.required_version('4.27.0') ]]] +[[[ macros.return_type('member') ]]] + +Get the member who created (owns) a thread channel. This works with regular threads and forum posts. + +=== "Examples" + + ```applescript + set {_owner} to owner of event-threadchannel + set {_creator} to thread owner of {_thread} + + # Example: Send a message to the thread owner + on thread create: + set {_owner} to owner of event-threadchannel + send "Thank you for creating this thread!" to {_owner} + ``` + +=== "Patterns" + + ```applescript + [the] [thread] owner of %threadchannel% + %threadchannel%'[s] [thread] owner + ``` + +## Thread Message Count + +[[[ macros.required_version('4.27.0') ]]] +[[[ macros.return_type('integer') ]]] + +Get the total number of messages in a thread channel. This includes all messages, not just visible ones. + +=== "Examples" + + ```applescript + set {_count} to message count of event-threadchannel + set {_total} to thread message count of {_thread} + + # Example: Display thread statistics + discord command threadstats : + prefixes: ! + trigger: + set {_thread} to thread channel with id arg-1 + set {_count} to message count of {_thread} + set {_owner} to owner of {_thread} + + reply with "Thread has %{_count}% messages and was created by %discord name of {_owner}%" + ``` + +=== "Patterns" + + ```applescript + [the] [thread] message count of %threadchannel% + %threadchannel%'[s] [thread] message count + ``` + ## Guild Bot's Role [[[ macros.required_version('4.16.0') ]]] diff --git a/docs/guild/forums.md b/docs/guild/forums.md index 9a0b1b0..373d150 100644 --- a/docs/guild/forums.md +++ b/docs/guild/forums.md @@ -23,6 +23,8 @@ set {_threads::*} to threads of forum with id "000" * As a thread channel, you can use the `retrieve messages` effect to get the messages * As a member container, `members of` expression is available to get active members of the post * You can get the tags of a thread using `tags of `. Keep in mind this will only work with **posts' threads!** +* You can get the **owner** of a thread using [`thread owner of `](../docs/expressions.md#thread-owner) - useful to know who created the post +* You can get the **message count** using [`message count of `](../docs/expressions.md#thread-message-count) - helpful for tracking post activity ## Tags @@ -52,3 +54,42 @@ Now, you'll be able to add it to the post for instance: ```applescript add {_created} to tags of thread channel with id "000" ``` + +## Working with Thread Information + +Since DiSky v4.27.0, you can access additional thread information to build more interactive features: + +```applescript +# Example: Display comprehensive thread statistics +discord command threadinfo : + prefixes: ! + trigger: + set {_thread} to thread channel with id arg-1 + if {_thread} is not set: + reply with ":x: Thread not found!" + stop + + set {_owner} to thread owner of {_thread} + set {_count} to message count of {_thread} + set {_tags::*} to tags of {_thread} + set {_members::*} to members of {_thread} + + make embed: + set title of embed to "Thread Information" + set description of embed to "**Thread:** %discord name of {_thread}%" + add field named "Owner" with value "%mention tag of {_owner}%" to embed + add field named "Messages" with value "%{_count}%" to embed + add field named "Active Members" with value "%size of {_members::*}%" to embed + if size of {_tags::*} > 0: + add field named "Tags" with value "%join {_tags::*} with "", ""%"" to embed + set color of embed to cyan + + reply with last embed +``` + +!!! tip "Reference Documentation" + For more details on these expressions, check out: + + * [Thread Owner Expression](../docs/expressions.md#thread-owner) - Get who created a thread + * [Thread Message Count Expression](../docs/expressions.md#thread-message-count) - Get the number of messages in a thread + * [Thread Tags Expression](../docs/expressions.md#tags) - Get the tags applied to a thread diff --git a/docs/interactions/slash-structure.md b/docs/interactions/slash-structure.md index 8f96248..7862480 100644 --- a/docs/interactions/slash-structure.md +++ b/docs/interactions/slash-structure.md @@ -50,6 +50,32 @@ This is the list of arguments your slash command will have. It works the same as An argument format is ``, and can be surrounded by `[]` to make it optional. +!!! success "Hyphen Support (v4.27.0+)" + Since DiSky v4.27.0, argument names can now include hyphens (`-`) for better readability! This is especially useful when you want to use multi-word argument names that follow Discord's naming conventions. + + **Examples:** + ```applescript + # Before v4.27.0 - You had to use underscores or camelCase + slash command userinfo : + # ... + + # Since v4.27.0 - You can use hyphens for clearer names + slash command userinfo : + description: Get information about a user + arguments: + target-user: The user to get information about + trigger: + reply with "Info for %discord name of arg-1%" + + # More examples with hyphens + slash command config : + arguments: + server-name: The name of the server + max-members: Maximum number of members + ``` + + For more details, see the [migration guide](../migrations/disky-v4-27.md#hyphen-support-in-slash-structure-arguments). + ## Command Groups and Subcommands DiSky supports organizing commands into groups and subcommands using a space-separated naming convention. You can create up to three levels of command hierarchy: diff --git a/docs/migrations/disky-v4-27.md b/docs/migrations/disky-v4-27.md new file mode 100644 index 0000000..405ccb6 --- /dev/null +++ b/docs/migrations/disky-v4-27.md @@ -0,0 +1,127 @@ +--- +icon: material/package-up +status: new +--- + +# DiSky v4.26 -> v4.27 + +DiSky v4.27.0 introduces new features and improvements for thread management, server tags, and slash command structures. This migration guide will help you update your DiSky scripts to be compatible with the new version. + +## New Features + +### Thread Owner and Message Count + +You can now retrieve the owner of a thread channel and get the total message count of a thread. These expressions work with thread channels, including forum posts. + +```applescript +# Get the owner of a thread +set {_owner} to owner of {_thread} +set {_owner} to thread owner of {_threadChannel} + +# Get the message count of a thread +set {_count} to message count of {_thread} +set {_msgCount} to thread message count of {_threadChannel} +``` + +**Use Cases:** +- Check who created a forum post +- Display thread statistics in embeds +- Moderate threads based on their creator +- Track activity in forum channels + +**Example - Forum Post Information:** +```applescript +on thread create: + set {_owner} to owner of event-threadchannel + set {_count} to message count of event-threadchannel + + send "New post created by %discord name of {_owner}% with %{_count}% message(s)" to channel with id "logs-channel-id" +``` + +### Member Equipped Server Tag + +Added support for retrieving a member's equipped server tag (also called "primary guild tag"). This feature allows you to access the tag that a user has chosen to display on their profile for a specific server. + +```applescript +# Get the equipped server tag of a user +set {_tag} to user tag of {_user} +set {_tag} to user primary guild tag of {_member} + +# Get the tag icon URL +set {_icon} to user tag icon of {_user} +set {_iconUrl} to user primary guild tag icon url of {_user} +``` + +!!! info "Server Tags" + Server tags are a Discord feature that allows users to choose a tag representing their identity or role in a server. The "equipped" tag is the one displayed on their profile. + +**Example - Display User Tag:** +```applescript +discord command profile []: + prefixes: ! + trigger: + set {_user} to arg-1 ? event-user + set {_tag} to user tag of {_user} + + if {_tag} is set: + set {_icon} to user tag icon url of {_user} + make embed: + set title of embed to "%discord name of {_user}%'s Profile" + set description of embed to "Equipped Tag: %discord name of {_tag}%" + set thumbnail of embed to {_icon} if {_icon} is set + reply with last embed + else: + reply with ":x: This user has no equipped server tag." +``` + +### Hyphen Support in Slash Structure Arguments + +You can now use hyphens (`-`) in slash structure argument names. Previously, this would cause parsing errors. + +**Before v4.27:** +```applescript +# This would cause an error +local slash command "test": + set description of command to "Test command" + add "user-name" as text argument named "name" to arguments of command # ❌ Error! +``` + +**Since v4.27:** +```applescript +# Now this works perfectly +local slash command "test": + set description of command to "Test command" + add "user-name" as text argument named "name" to arguments of command # ✅ Works! + add "max-count" as integer argument named "count" to arguments of command # ✅ Works! +``` + +!!! success "Improved Readability" + This enhancement allows for more readable argument names that follow Discord's naming conventions, especially when you want to separate words without using underscores or camelCase. + +**Example - Better Argument Names:** +```applescript +local slash command "user-info": + set description of command to "Get information about a user" + add "target-user" as user argument named "user" to arguments of command + add "show-avatar" as boolean argument named "avatar" to arguments of command + add "include-roles" as boolean argument named "roles" to arguments of command + register command + +on slash command: + if event-string is "user-info": + set {_user} to argument "user" as user + set {_showAvatar} to argument "avatar" as boolean + set {_includeRoles} to argument "roles" as boolean + + # Process command... +``` + +## Summary + +Version 4.27.0 focuses on quality-of-life improvements: + +- **Thread Management**: New expressions for thread owner and message count +- **Server Tags**: Access to equipped server tags for users +- **Better Slash Commands**: Hyphen support in argument names for clearer naming + +All these features are non-breaking and can be adopted gradually in your existing code. diff --git a/mkdocs.yml b/mkdocs.yml index 8ef9960..f1f83b9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -135,6 +135,7 @@ nav: - 'From DiSky v4.2X to v4.24': migrations/disky-v4-24.md - 'From DiSky v4.2X to v4.25': migrations/disky-v4-25.md - 'From DiSky v4.2X to v4.26': migrations/disky-v4-26.md + - 'From DiSky v4.2X to v4.27': migrations/disky-v4-27.md - 'Examples': - 'Core': examples/core.md - 'Components': examples/components.md