Variables
This guide will tell you about what variables are, what the principles and mechanics underlying them are, and also describes all the possible ways to work with them in @MenuBuilderBot.
❖ Variables - what are they?
Variable - (in @MenuBuilderBot) is a kind of container for storing data (text or numeric). A more detailed description of the concept of variables.
How to add variables to the bot
Functionality of "🧩Extensions " section: for additional variables to appear, they must be activated in your bot.
Additional variables.
To connect, go in your bot:☞ 🔐Admin | 🧩Extensions | 📂Variables
After activating the required number of additional variables, go to:☞ 🔐Admin |🗄Variables
and after selecting the desired Type of variable, add it by specifying the desired Name. Only then can the new variable be considered fully created.
To edit a variable, go inside the button with its name. Depending on the Type of a chosen variable, you can:
● Change the name of a variable (respectively, its macro).
● Change the displayed name (used in system messages that cannot be edited).
● Enable user notification about data changes in a variable (custom message available, see below).
● Enable "Top by variable" (if this function is activated in the bot).
● Add a comment (useful when you have a lot of variables in the bot).
● Set the default value
Custom variable notification
Custom message about changing the value of a variable.
Functionality of the "🧩Extensions" section: Allows you to set your own message for the user about changing the value of the Variable.
Custom variable message.
To connect, go to your bot:☞ 🔐Admin | 🧩Extensions | 📂Customization
After activating the option in Extensions, you can set a Variable's Custom Notification Message:
☞ 🔐Admin | 🗄 Variables
• Select Variable Type
• Specify a variable
• Click «Set Notify Message».
Variable types
As of today, there are 5 types of variables in @MenuBuilderBot:
Text variable
This is a container for text. It can contain both Letters, Emoji and Numbers (as text). This variable can contain individual user data (for example, his wallet address). While working with Text Variables in Expressions, quotes must be used.
● Default value: None.
● Size: 200 characters.
Numeric variable
Can only contain numbers. This allows the contents of this variable to be manipulated like a regular number (while taking a value, such a variable checks if the value is a number). Balance is an example of a numeric variable.
● Default value: 0 (zero).
Global variable
The main feature of that variable is that it has the same value for all users. Thus, changing its value once will simultaneously change it for all users of the bot. Global Variables themselves are Text Variables (see above), however they can contain Media Content (Pictures, Audio, Video) same as Media Variables (see below).
● Default value: None.
● Size: 200 characters.
Time (Date) variable
Contains date-time data recorded in a specific (text) format.
● Recording format: "17.05.2020 19:45:05".
● Default value: System time "Now" same as it is in dt_now() function.
Technically speaking, Time in this format can be stored in Text Variables, but you will not be able to fully work with such variables. In the Text variable, Time can only be stored, but no actions can be performed with any of such variables.
Media variable
It can contain any kind of media - pictures, videos, stickers, audio and other. The Media Variable is a Text Variable - for this reason, it works the same way as Text Variables (see the Expressions manual for Text Variables).
● Default value: None.
At the moment, to change the value of the Media Variable - you can only by using the Form in the «Variable Input» mode.
Displaying the value of the Media variable in the message.
1. Go to the «Post Editor» and create a message (as usual) or use a ready-made message for this.
2. Go to «Message settings» by clicking on the button with an asterisk ("*")
3. Select the «Media Variable» option
• Specify a variable from the list
• Specify whether to show Media from the Post itself (if any) if the variable is empty?
IMPORTANT: When using variables containing media content, keep in mind that in Telegram a "message with a picture" is in fact a picture with a caption... However, not every media content (for example, a sticker) can contain a caption - thus, if you have a message with text and the picture for it is taken from the variable, then this text may be absent depending on type of the media content is currently saved in this variable.
IMPORTANT: keep in mind that if your variable is empty and there is no text in the message, then the bot will show --Error--. The bot should show a message, but there is no data for it - so the constructor will substitute it with the error text.
Variable of Formulas
Variable of Formulas - contains formulas or parts of other Expressions. Used in Expressions as a Macros. The contents of the Formula Variable are substituted into the Final Expression at destination as text and are eventually evaluated and processed in the Final Expression at destination. The main purpose of the Formula Variable is to reduce the length and simplify the understanding of the Final Expression at destination, as well as to simplify the process of changing the uniform formulas used in different parts of the bot.
● Default value: None.
A Variable of Formulas is technically a Global Variable.
You can write into it:
• Text
• Numbers
• Symbols of mathematical operations
• Macros
THE MAIN FEATURE of this variable is that all the necessary values (for example, Macros values) in it are prepared in advance - forming a ready-made Formula, BEFORE the text of the Variable itself is substituted into the Final Expression at destination.
Technically, in the Final Expression, the processed value of the Formula Variable is substituted FIRST - BEFORE all other substitutions and proceedings. Therefore, it can contain different Macros and parts of the Final Expression that you need, which (AFTER substitution in the formula) will be placed and finally processed in the Final Expression at destination. This allows you to make sure that all the necessary values will be substituted and processed - whereas when using a regular Global Variable, errors are possible.
IMPORTANT: The Variable of Formulas is NOT an Expression in the full sense, but rather is a part of it - the {Curly Brackets} are NOT ALLOWED in it. There is no point in using it other than as part of another Expression.
FOR EXAMPLE:
Variable: var with a value %rate% * 1.2
Variable: invest with a value 5
Expression: {%invest% * %var%}
If the variable var is a Variable of Formulas, then the Expression BEFORE parsing will be brought to the form such as: {%invest% * %rate% * 1.2} - that is, its value will be substituted in advance - before substituting the values of the main Macros of the expression itself. In the case of regular Global Variable, we would receive {5 * %rate% * 1.2} and an expression parsing error.
Variables peculiarities
Below is a list of feature common to all variables. Each type of variable has its own characteristics - for this reason, some of the features may be absent, in one case or another...
● Data in variables can be individual for each user, as well as global - common to all.
● The data in the variable can be changed: Only by Admin, Admin and User together, By pressing the buttons or direct data input through Forms.
● Each variable has a Name for accessing its data.
● Each variable has a macros for displaying its value (to the user or administrator, for using in Expressions and Conditions) based on its name.
● Each variable can be in two states: Initialized and NOT initialized.
● Each new variable is NOT initialized - does not contain and have never contained any value - shows its default value.
● A variable is initialized by assigning a value or by an Action of Initialization.
● There are only three ways to return an Initialized variable to its original (NOT initialized) state: 1. Delete via the variable editor or by /vardel command. 2. Clean it up with the /varclearall command. 3. To use the Action of Clearing. Assigning a default value to an Initialized variable will NOT make it NOT initialized again.
● In functions where you need to specify a variable, the list will contain only variables which this function can work with (means, probably, not all you have).
● The variables, in the lists, are sorted alphabetically (therefore, by specifying the same prefixes, individual variables can be "kept" in the required parts of the list).
● The lists first come with the sorted Individual variables, and then the sorted Global variables.
❖ Variable management
There are several ways to manipulate variables.
1. Admin Commands
2. User Input
3. Variable Editor
4. Buttons and Actions
Using Commands to Work with Variables
A manual value control module is connected to the variables, it receives composite commands.
In general, the command looks like this:/command var_name user_id value
For NUMERIC variables, a comment can be added after the value in the command. The user will receive the text of the comment along with the message about the change of the variable - regardless of the settings of the notification itself.
In general, a command with a comment looks like this:/command var_name user_id value comment
The comment must begin on the same line as the command itself - inside the comment, line breaks are allowed.
Where: / (Slash, Slash) - any command starts with a "/" sign.command is the command itself.var_name is the name of the variable.user_id - Telegram ID or UserCode of the bot user.value or delta this is the value to use.comment - the text of the comment.
All arguments to a composite command must be separated by a SPACE (not on a new line).
Example 1 (without line break):/varadd balance 888888 1 text
Example 2 (with line break):/varset balance 888888 0 text1text2
Comment can also be added in Variables Editor. See the Basics of balance management and variable's editor for more details.
Commands work without confirmation and their action are irreversible.
The package of Commands for individual processing of variables
REQUEST the value of a variable. The bot will simply send the value of the variable. No changes will be made.
SET the value of a variable. The bot will overwrite the old value in the variable regardless of the state.
ADD value to variable (to subtract - use negative value). The bot will add the value specified in the command to the existing one in the variable.
Works only with Numeric variables.
DELETE the value of the variable for specified user. Will remove any existing value in the variable, bringing it back to its original state for one user.
This command makes the variable NOT initialized again. Read more about initialization in the "Action of Initialization" guide.
TOTAL SUM of variable data for all users of the bot.
Works only with Numeric variables.
The package of Commands for bulk processing of variables:
CLEAR DATA of this variable for ALL users.
This command makes the variable NOT initialized again. Read more about initialization in the "Action of Initialization" guide.
IMPORTANT: Be careful, the action is irreversible and works without confirmation.
HOW MANY VALUES ARE IN TOTAL in this variable (for how many users this variable was initialized).
ADDS "value" TO ALL VALUES OF ALL users who have this variable initialized (use a negative number for subtraction of value).
The command /varaddall consumes "Tokens of Functions". The number of tokens consumed is equal to the number of values that will be changed. In order for deducted number of tokens does not come as a surprise - the number of values can (and should) be found out using /varcountall command. It, first of all, was created for this purpose.
MULTIPLIES ALL VALUES OF ALL users, who have this variable initialized, by "value".
The command /varaddall consumes "Tokens of Functions". The number of tokens consumed is equal to the number of values that will be changed. In order for deducted number of tokens does not come as a surprise - the number of values can (and should) be found out using /varcountall command. It, first of all, was created for this purpose.
Mass changes are NOT recorded in the variable change logs.
For those who are not into mathematics: to add a percentage, use /varmultall, and count value like this:
1 + percentage / 100.
For example, add 10% to your balance:/varmultall balance 1.1
ONCE AGAIN: ALL commands of the package will work ONLY WITH THOSE USERS and THOSE VARIABLES THAT ARE INITIALIZED. If you have a thousand users, and the balance is initialized for three of them, it will work for these three ONLY!
ONCE AGAIN: NO, with the help of these commands you CANNOT assign any value to ALL users. Until their variable is initialized.
Example of a command:
• Name of a text variable - rank
• ID (UserCode) of a user - 111222333
• Data of a variable - "Any text"
The command /varset will look like this: /varset rank 111222333 Any text
Each parameter in command must be separated with a SPACE, in ONE LINE, and not on a new line.
The user sets the value
You can let the user himself to set the value of a particular variable. In other words: accept data from the user and store it in a variable. For example, to enter his crypto-wallet address, e-mail address or other personal data.
It works like the Question in QnA chat, the only difference is that user's answer goes directly to the variable, and not to the admin.
The creation of a variable input is done via:☞ 📝Post Editor > Add Variable Input
The add button will appear only if there is at least one variable other than "balance".
Read more in "Feedback Forms" guide.
Changing the value of a numeric variable using the Editor.
The value of any NUMERIC variable can be changed using the editor identical to the Balance editor. This editor can be assigned to any button anywhere in the menu.
Learn more about creating a variable editor.
Changing values using Buttons and Actions
Bonus and Exchange buttons.
To connect, go in your bot:☞ 🔐Admin | 🧩Extensions | 📂Buttons
Actions.
To connect, go in your bot:☞ 🔐Admin | 🧩Extensions | 📂Actions
Bonus button
Allows users to accrue a bonus (the number of conventional units specified by the admin) to the selected variable (for example, Balance). A feature of this button is that the Admin can set the Period for the user to receive a bonus (the time between bonuses, if you wish). That is, the frequency with which the User can receive the Bonus by pressing the button. The variable for accrual, Amount and Frequency (in hours - in whole or fractional numbers) is specified by the admin when creating the button itself. All parameters can be set by Macros.
The Bonus button can change ONE variable at a time.
Fix Exchange 1 button
Allows users to exchange a fixed amount in conventional units within the bot, transferring the amount preset by the admin from one variable to another. The button SUBTRACTS a given amount from one variable and ADDS to another - thereby carrying out the exchange of funds. All parameters can be set by Macros.
The "Fix Exchange 1" button changes TWO variables in one click.
This button can also be used in a different way. For example, despite the fact that one of the numbers is always subtracted, you can also add both numbers in two different variables. If you subtract a negative number, then in fact it will be added. Different interesting mechanics can be built using this trick.
Course Exchange 2 button
Allows users to exchange the amount in conventional units, using rate, within the bot, transferring the amount from one variable to another, taking into account the exchange rate specified by the Admin. The button SUBTRACTS the specified amount from one variable and, after calculating using rate, ADDS it to another - thereby carrying out the exchange of funds. For calculations, the specified exchange rate is used, this rate can also be taken from a variable (the exchange rate can be updated automatically (using auto updated currency rates - see below) and modified using Expressions). All parameters can be set by Macros.
The "Course Exchange 2" button changes TWO variables in one click.
Currency rates.
To connect, go in your bot:
☞ 🔐Admin | 🧩Extensions | 📂Logs and Data
Actions and variables
Action in @MenuBuilderBot is a way to perform one action. One Action (as a term) - meas one action in fact. Actions can be different - change the value of a variable, check a condition, add percentage to the referral, etc. Actions in buttons can be combined to create unique algorithms and sequences of actions, thereby obtaining the desired functionality. The Guide on Actions is voluminous, but worth reading.
A button with Action has no restrictions in its use and can change as many variables as needed in one click.
❖ Variables in expressions and conditions
The values of variables with the help of macros can be used in the calculation by substituting them into the Expressions, as well as in Conditions of buttons and Actions. Detailed descriptions of each of the cases are referenced in the text links. Expressions can be used both in bot messages and in button functions.
As a reminder, variable names are case sensitive. That is, the variables named "Var" and "var" are two different variables.
❖ Working with variable values
Displaying values to the user
In order to show the variable's value to the user, it is enough to insert a macros with the name of this variable in the desired message. Macros is a variable's name surrounded by percent "%" signs.
For example, a macro %wallet%
will show the value of the variable "wallet".
In the text of one variable, you can use macros of other variables.
Exporting Variable Values
Variable data can be exported to a .csv file. To export, you need the user to have referrals, balance, or something else - bonuses, for example.
Read more about conditions and how to work with the function in the Export guide.
IMPORTANT: The data of those who just came "to have look" and pressed few menu buttons - will not be exported.
ATTENTION: one exported file will contain ALL available data of ALL available users.
EXCEPT THOSE Above!!!!!!!!!!!!!
Export of user data.
To connect, go in your bot:
☞ 🔐Admin | 🧩Extensions | 📂Logs and DataExport is connected to 1 bot.
An example of an export file in our news channel:
https://t.me/MenuBuilderNews/296
Balance transactions log
In order to improve the security and stability of data in the accrual system, and to resolve possible user disputes on the balance variables in the bot, it is possible to logging each transaction in a file, by sequentially recording in a spreadsheet all transactions for the variable balance in your bot.
For details and conditions of connection, see your bot
Balance log.
To connect, go in your bot:
☞ 🔐Admin | 🧩Extensions | 📂Logs and DataLogging is connected to 1 bot.
An example of a Log export file in our news channel:
https://t.me/MenuBuilderNews/297
Ref. Parent data for Media Variable
The media variable can take Ref Parent's data to show to his referral. For example, if you need to show a referral a photo of his referral parent added by him to his profile. This feature requires activation of the extension.
Referral Parent's Data
To connect, go in your bot:
☞ 🔐Admin | 🧩Extensions | 📂Logs and Data