✨ Access any giveaway property in giveaway messages (#302)

Co-authored-by: Androz <androz2091@gmail.com>

README.md

@@ -105,7 +105,7 @@ client.on('interactionCreate', (interaction) => {
 ```
 
 -   **options.time**: the giveaway duration.
--   **options.prize**: the giveaway prize.
+-   **options.prize**: the giveaway prize. You can [access giveaway properties](https://github.com/Androz2091/discord-giveaways#access-giveaway-properties-in-messages).
 -   **options.winnerCount**: the number of giveaway winners.
 -   **[and many other optional parameters to customize the giveaway - read documentation](https://discord-giveaways.js.org/global.html#GiveawayStartOptions)**
 
@@ -146,7 +146,7 @@ client.on('interactionCreate', (interaction) => {
 ```
 
 -   **options.winnerCount**: the number of winners to pick.
--   **options.messages**: an object with the "congrat" and the "error" message. [Usage example](https://github.com/Androz2091/discord-giveaways#-translation)
+-   **options.messages**: an object with the "congrat" and the "error" message. [Usage example](https://github.com/Androz2091/discord-giveaways#-translation).
 
 <a href="http://zupimages.net/viewer.php?id=19/24/mhuo.png">
     <img src="https://zupimages.net/up/19/24/mhuo.png"/>
@@ -172,12 +172,12 @@ client.on('interactionCreate', (interaction) => {
 });
 ```
 
--   **options.newWinnerCount**: the new number of winners.  
--   **options.newPrize**: the new prize.  
+-   **options.newWinnerCount**: the new number of winners.
+-   **options.newPrize**: the new prize. You can [access giveaway properties](https://github.com/Androz2091/discord-giveaways#access-giveaway-properties-in-messages).
 -   **options.addTime**: the number of milliseconds to add to the giveaway duration.
 -   **options.setEndTimestamp**: the timestamp of the new end date (for example, for the giveaway to be ended in 1 hour, set it to `Date.now() + 60000`).
--   **options.newMessages**: the new giveaway messages. Will get merged with the existing object, if there.
--   **options.newExtraData**: the new extra data value for the giveaway
+-   **options.newMessages**: the new giveaway messages. Will get merged with the existing object, if there. You can [access giveaway properties](https://github.com/Androz2091/discord-giveaways#access-giveaway-properties-in-messages).
+-   **options.newExtraData**: the new extra data value for the giveaway.
 -   **options.newBonusEntries**: the new BonusEntry objects (for example, to change the amount of entries).
 -   **options.newLastChance**: the new options for the last chance system. Will get merged with the existing object, if there.
 
@@ -307,7 +307,6 @@ The reason for this is that, in JavaScript, all numbers are [IEEE double precisi
 But snowflakes can have more than 16 digits, which means that if you would access them like in the example above, the last digits of the snowflake would get messed up.  
 _The special format would "convert" the external string snowflake into a number, that is why we talk about digits here._
 
-
 ### Last Chance
 
 ```js
@@ -325,7 +324,7 @@ client.giveawaysManager.start(interaction.channel, {
 ```
 
 -   **lastChance.enabled**: if the last chance system is enabled.
--   **lastChance.content**: the text of the embed when the last chance system is enabled.
+-   **lastChance.content**: the text of the embed when the last chance system is enabled. You can [access giveaway properties](https://github.com/Androz2091/discord-giveaways#access-giveaway-properties-in-messages).
 -   **lastChance.threshold**: the number of milliseconds before the giveaway ends when the last chance system will be enabled.
 -   **lastChance.embedColor**: the color of the embed when last chance is enabled.
 
@@ -350,7 +349,7 @@ client.giveawaysManager.start(interaction.channel, {
 ```
 
 -   **pauseOptions.isPaused**: if the giveaway is paused.
--   **pauseOptions.content**: the text of the embed when the giveaway is paused.
+-   **pauseOptions.content**: the text of the embed when the giveaway is paused. You can [access giveaway properties](https://github.com/Androz2091/discord-giveaways#access-giveaway-properties-in-messages).
 -   **pauseOptions.unPauseAfter**: the number of milliseconds after which the giveaway will automatically unpause.
 -   **pauseOptions.embedColor**: the color of the embed when the giveaway is paused.
 
@@ -405,6 +404,25 @@ The reason for this is that, in JavaScript, all numbers are [IEEE double precisi
 But snowflakes can have more than 16 digits, which means that if you would access them like in the example above, the last digits of the snowflake would get messed up.  
 _The special format would "convert" the external string snowflake into a number, that is why we talk about digits here._
 
+### Send embed as message
+
+You can send an embed instead of, or with the normal message for the following messages:  
+`giveaway.messages.winMessage`, `GiveawayRerollOptions.messages.congrat`, `GiveawayRerollOptions.messages.error`.
+
+The format looks like this: `message: { content: '', embed: new Discord.MessageEmbed() }`
+
+You can [access giveaway properties](https://github.com/Androz2091/discord-giveaways#access-giveaway-properties-in-messages) in all embed properties that are a string.
+
+### Access giveaway properties in messages
+
+You can access any giveaway property inside of giveaway messages with the format: `{this.<property>}`.  
+For example: `messages: { winMessage: 'Congratulations, {winners}! You won **{this.prize}**!\n{this.messageURL}' }`.
+
+Also, you can write javascript code inside of the `{}`.  
+For example: `messages: { winMessage: 'Congratulations, {winners}! You won **{this.prize.toUpperCase()}**!\n{this.messageURL}' }`.
+
+If you want to fill in strings that are not messages of a giveaway, or just custom embeds, then you can use `giveaway.fillInString(string)` for strings and `giveaway.fillInEmbed(embed)` for embeds.
+
 ## 🇫🇷 Translation
 
 You can also pass a `messages` parameter for `start()` function, if you want to translate the bot text:
@@ -413,7 +431,7 @@ You can also pass a `messages` parameter for `start()` function, if you want to
 -   **options.messages.giveawayEnded**: the message that will be displayed above the embeds when the giveaway is ended.
 -   **options.messages.drawing**: the message that displays the drawing timestamp.
 -   **options.messages.inviteToParticipate**: the message that invites users to participate.
--   **options.messages.winMessage**: the message that will be displayed to congratulate the winner(s) when the giveaway is ended.
+-   **options.messages.winMessage**: the message that will be displayed to congratulate the winner(s) when the giveaway is ended. You can [send an embed instead of, or with the normal message](https://github.com/Androz2091/discord-giveaways#send-embed-as-message).
 -   **options.messages.embedFooter**: the message displayed at the bottom of the embeds. [Can be deactivated and iconURL can be set](https://discord-giveaways.js.org/global.html#EmbedFooterObject).
 -   **options.messages.noWinner**: the message that is displayed if no winner can be drawn.
 -   **options.messages.winners**: simply the word "winner" in your language.
@@ -431,30 +449,35 @@ client.giveawaysManager.start(interaction.channel, {
         giveawayEnded: '🎉🎉 **GIVEAWAY ENDED** 🎉🎉',
         drawing: 'Drawing: {timestamp}',
         inviteToParticipate: 'React with 🎉 to participate!',
-        winMessage: 'Congratulations, {winners}! You won **{prize}**!\n{messageURL}',
+        winMessage: 'Congratulations, {winners}! You won **{this.prize}**!\n{this.messageURL}',
         embedFooter: 'Powered by the discord-giveaways package',
         noWinner: 'Giveaway cancelled, no valid participations.',
-        hostedBy: 'Hosted by: {user}',
+        hostedBy: 'Hosted by: {this.hostedBy}',
         winners: 'winner(s)',
         endedAt: 'Ended at',
     }
 });
 ```
 
+You can [access giveaway properties](https://github.com/Androz2091/discord-giveaways#access-giveaway-properties-in-messages) in all these messages (except for the "units" object).
+
 And for the `reroll()` function:
 
 ```js
 client.giveawaysManager.reroll(messageId, {
         messages: {
-            congrat: ':tada: New winner(s): {winners}! Congratulations, you won **{prize}**!\n{messageURL}',
+            congrat: ':tada: New winner(s): {winners}! Congratulations, you won **{this.prize}**!\n{this.messageURL}',
             error: 'No valid participations, no new winner(s) can be chosen!'
         }
     });
 ```
 
--   **options.messages.congrat**: the congratulatory message.  
+-   **options.messages.congrat**: the congratulatory message.
 -   **options.messages.error**: the error message if there is no valid participant.
 
+You can [access giveaway properties](https://github.com/Androz2091/discord-giveaways#access-giveaway-properties-in-messages) in these messages.  
+You can [send embeds instead of, or with the normal messages](https://github.com/Androz2091/discord-giveaways#send-embed-as-message).
+
 ## Custom Database
 
 You can use your custom database to save giveaways, instead of the json files (the "database" by default for `discord-giveaways`). For this, you will need to extend the `GiveawaysManager` class, and replace some methods with your custom ones. There are 4 methods you will need to replace:

examples/custom-databases/mongoose.js

@@ -37,7 +37,7 @@ const giveawaySchema = new mongoose.Schema({
         giveawayEnded: String,
         inviteToParticipate: String,
         timeRemaining: String,
-        winMessage: String,
+        winMessage: mongoose.Mixed,
         embedFooter: mongoose.Mixed,
         noWinner: String,
         winners: String,

src/Constants.js

@@ -7,25 +7,26 @@ const Discord = require('discord.js');
  * @property {string} [giveaway='🎉🎉 **GIVEAWAY** 🎉🎉'] Displayed above the giveaway embed when the giveaway is running.
  * @property {string} [giveawayEnded='🎉🎉 **GIVEAWAY ENDED** 🎉🎉'] Displayed above the giveaway embed when the giveaway has ended.
  * @property {string} [inviteToParticipate='React with 🎉 to participate!'] Displayed in the giveaway embed. Invite people to react to the giveaway.
+ * @property {string|MessageObject} [winMessage='Congratulations, {winners}! You won **{this.prize}**!\n{this.messageURL}'] Sent in the channel when the giveaway is ended.
  * @property {string} [drawing='Drawing: {timestamp}'] Displayed below "inviteToParticipate" in the giveaway embed. "{timestamp}" will be replaced automatically with the time remaining.
  * @property {string} [winMessage='Congratulations, {winners}! You won **{prize}**!\n{messageURL}'] Sent in the channel when the giveaway is ended.
  * @property {string|EmbedFooterObject} [embedFooter='Powered by the discord-giveaways package'] The footer of the giveaway embed.
  * @property {string} [noWinner='Giveaway cancelled, no valid participations.'] Displayed in the giveaway embed when there is no valid winner for the giveaway.
  * @property {string} [winners='winner(s)'] Displayed next to the embed footer, used to display the number of winners of the giveaways.
  * @property {string} [endedAt='Ended at'] Displayed next to the embed footer, used to display the giveaway end date.
- * @property {string} [hostedBy='Hosted by: {user}'] Below the "inviteToParticipate" message, in the description of the embed.
+ * @property {string} [hostedBy='Hosted by: {this.hostedBy}'] Below the "inviteToParticipate" message, in the description of the embed.
  */
 exports.GiveawayMessages = {
     giveaway: '🎉🎉 **GIVEAWAY** 🎉🎉',
     giveawayEnded: '🎉🎉 **GIVEAWAY ENDED** 🎉🎉',
     inviteToParticipate: 'React with 🎉 to participate!',
+    winMessage: 'Congratulations, {winners}! You won **{this.prize}**!\n{this.messageURL}',
     drawing: 'Drawing: {timestamp}',
-    winMessage: 'Congratulations, {winners}! You won **{prize}**!\n{messageURL}',
     embedFooter: 'Powered by the discord-giveaways package',
     noWinner: 'Giveaway cancelled, no valid participations.',
     winners: 'winner(s)',
     endedAt: 'Ended at',
-    hostedBy: 'Hosted by: {user}',
+    hostedBy: 'Hosted by: {this.hostedBy}'
 };
 
 /**
@@ -36,6 +37,14 @@ exports.GiveawayMessages = {
  * @property {string} [iconURL] The icon URL of the footer.
  */
 
+/**
+ * Message object.
+ * @typedef MessageObject
+ *
+ * @property {string} [content] The raw message
+ * @property {Discord.MessageEmbed|Discord.MessageEmbedOptions} [embed] The embed
+ */
+
 /**
  * The start options for new giveaways.
  * @typedef GiveawayStartOptions
@@ -145,13 +154,13 @@ exports.GiveawaysManagerOptions = {
  *
  * @property {number} [winnerCount=giveaway.winnerCount] The number of winners to pick.
  * @property {Object} [messages] The messages used in this method.
- * @property {string} [messages.congrat=':tada: New winner(s): {winners}! Congratulations, you won **{prize}**!\n{messageURL}'] The message used if there are new winners.
- * @property {string} [messages.error='No valid participations, no new winner(s) can be chosen!'] The message used if no new winner(s) could be chosen.
+ * @property {string|MessageObject} [messages.congrat=':tada: New winner(s): {winners}! Congratulations, you won **{this.prize}**!\n{this.messageURL}'] The message used if there are new winners.
+ * @property {string|MessageObject} [messages.error='No valid participations, no new winner(s) can be chosen!'] The message used if no new winner(s) could be chosen.
  */
 exports.GiveawayRerollOptions = {
     winnerCount: null,
     messages: {
-        congrat: ':tada: New winner(s): {winners}! Congratulations, you won **{prize}**!\n{messageURL}',
+        congrat: ':tada: New winner(s): {winners}! Congratulations, you won **{this.prize}**!\n{this.messageURL}',
         error: 'No valid participations, no new winner(s) can be chosen!'
     }
 };