Forms!

Author: ALCC01

docs/objects/Bot.rst

@@ -237,4 +237,41 @@ This object represents a Telegram bot.
     :param string filter: Must be one of the following: ``private``, ``group``, ``supergroup``, ``channel`` or ``all``. Can also be a function that accepts one argument (a :doc:`Chat` object without functions) and returns a boolean value
     :param function callback: A function to which is provided a single argument, a promise that resolves to a :doc:`Chat` object.
 
-    Iterates a function through all of chats stored in the profiles storage.
+    Iterates a function through all of chats stored in the profiles storage.
+
+.. js:function:: form(user_id, object, callback)
+
+    :param string user_id: Can also be a :doc:`Chat` or a :doc:`User` object. **It must be a private chat!**
+    :param object object: The form object (see below).
+    :param function callback: A function that accept one argument
+
+    Creates a form for a user. The ``object`` argument must follow this format:
+
+    .. code-block:: javascript
+
+        {name: {
+            message: {
+                text: 'Please enter your name',
+                options: {}
+            },
+            regex: /([A-Z]){1,20}/,
+            error: {
+                text: 'Your name must be between 1 and 20 letters long and must contain only letters',
+                options: {}
+            }
+        },
+        surname: {
+            message: {
+                text: 'Please enter your surname',
+                options: {}
+            },
+            regex: /([A-Z]){1,20}/,
+            error: {
+                text: 'Your surname must be between 1 and 20 letters long and must contain only letters',
+                options: {}
+            }
+        }
+
+.. js:function:: removeForm(user_id)
+
+    :param string user_id: Can also be a :doc:`Chat` or a :doc:`User` object. **It must be a private chat!**

docs/objects/CallbackQuery.rst

@@ -15,7 +15,7 @@ This object represents a Telegram callback query.
 
 Creates a new CallbackQuery object.
 
-.. js:function:: answerCallbackQuery(text, alert)
+.. js:function:: answer(text, alert)
 
     :param string text:
     :param boolean alert: Whether the user should be shown an alert

docs/quickstart.rst

@@ -71,7 +71,7 @@ chat) as an argument.
 
 .. warning::
 
-    A ``message`` event will be emitted even if a command or a service message event is triggered! Make sure
+    A ``message`` event will be emitted even if a service message event is triggered! Make sure
     to not produce unintended behaviors
 
 ********
@@ -323,4 +323,42 @@ Nodeogram provides a simple way for you and your bot to keep track of the users
 its profile management interface. If a bot is instantiated with ``profiles_path`` in its options, it will start saving
 basic information about any user and chat he will become aware of.
 
-The ``broadcast()`` function will enable you to easily access that data and interact with your users.
+The ``broadcast()`` function will enable you to easily access that data and interact with your users.
+
+=====
+Forms
+=====
+
+Nodeogram enables you to ask your users questions and receive responses in an ordinated fashion. Creating a form for a user
+will make the bot ignore any event for his chat until he answers every question. Once every question is answered, answers
+are returned to you via a callback. Nodeogram also makes sure that the answers provided are acceptable for you bot, checking
+if they match a regular expression (regex).
+
+.. code-block:: javascript
+
+    bot.form(message.from, {
+        name: {
+            message: {
+                text: 'Please enter your name',
+                options: {}
+            },
+            regex: /([A-Z]){1,20}/,
+            error: {
+                text: 'Your name must be between 1 and 20 letters long and must contain only letters',
+                options: {}
+            }
+        },
+        surname: {
+            message: {
+                text: 'Please enter your surname',
+                options: {}
+            },
+            regex: /([A-Z]){1,20}/,
+            error: {
+                text: 'Your surname must be between 1 and 20 letters long and must contain only letters',
+                options: {}
+            }
+        }
+    }, (result) => {
+        message.from.sendMessage(`Your name is ${result.name} ${result.surname}`)
+    })

examples/redditlivebot/app.js

@@ -2,7 +2,7 @@
 const nodeogram = require('nodeogram'),
     WebSocketClient = require('websocket').client,
     config = require('./config.json'),
-    bot = new nodeogram.Bot(config.token, {profiles_path: __dirname + '/profiles.json', enableHelp: false}),
+    bot = new nodeogram.Bot(config.token, {profiles_path: __dirname + '/profiles.json', enableHelp: true}),
     request = require('superagent-promise')(require('superagent'), Promise);
 
 var threads = {}, // thread_id: [user_id, ...]

lib/Bot.js

@@ -27,6 +27,7 @@ function Bot(token, options) {
     this.saveUsers = true;
     this.saveChats = true;
     this.enableHelp = true;
+    this.forms = {}; // user_id: {form, answers}
     extend(this, options);
 
     this.handleAPIError = (err) => {
@@ -101,8 +102,12 @@ function Bot(token, options) {
                                 return;
                             }
                             var message = new Message(result.message, this);
+                            var handleNext = true;
                             this.messageHandlers.forEach((handler) => {
-                                handler(message);
+                                if (handleNext) {
+                                    var res = handler(message);
+                                    handleNext = res === undefined ? true : res;
+                                }
                             });
                         }
                         if (result.inline_query) this.emitter.emit('inline_query', new InlineQuery(result.inline_query, this));
@@ -128,6 +133,25 @@ function Bot(token, options) {
         this.commands.push({command: command, description: description, callback: callback, hidden: hidden});
     };
 
+    this.form = (user_id, object, callback) => {
+        if (user_id instanceof Chat) user_id = user_id.id;
+        if (user_id instanceof User) user_id = user_id.id;
+        if (!this.forms[user_id]) {
+            this.forms[user_id] = {
+                form: object,
+                answers: {},
+                callback: callback
+            }
+        }
+        this.sendMessage(user_id, object[Object.keys(object)[0]].message.text, object[Object.keys(object)[0]].message.options)
+    };
+
+    this.removeForm = (user_id) => {
+        if (this.forms[user_id]) {
+            delete this.forms[user_id]
+        }
+    };
+
     this.getChat = (chat_id) => {
         return this.call('getChat', {chat_id: chat_id}).then((res) => {
             return new Chat(res.body.result, this)
@@ -399,14 +423,17 @@ function Bot(token, options) {
     };
 
     this.handleCommands = (message) => {
-        if (message.commands.length > 0) {
-            var command = message.commands[0];
+        var returm = true;
+        if (message.command) {
+            var command = message.command;
             this.commands.forEach((entry) => {
                 if (("/" + entry.command) == command.command && (!command.recipient || ("@" + this.me.username) == command.recipient)) {
                     entry.callback(command.args, message);
+                    returm = false;
                 }
             });
         }
+        return returm;
     };
 
     this.handleMessage = (message) => {
@@ -442,6 +469,40 @@ function Bot(token, options) {
         })
     };
 
+    this.handleForms = (message) => {
+        var id = message.from.id;
+        if (this.forms[id] && message.chat.type == 'private') {
+            var next = false;
+            var wait = false;
+            for (var key in this.forms[id].form) {
+                if (!next) {
+                    if (this.forms[id].form.hasOwnProperty(key) && !this.forms[id].answers.hasOwnProperty(key)) {
+                        var question = this.forms[id].form[key];
+                        if (question.regex.test(message.text)) {
+                            this.forms[id].answers[key] = message.text;
+                            next = true;
+                        } else {
+                            message.reply(question.error.text, question.error.options);
+                            wait = true;
+                            break;
+                        }
+                    }
+                } else {
+                    if (this.forms[id].form.hasOwnProperty(key)) {
+                        message.reply(this.forms[id].form[key].message.text, this.forms[id].form[key].message.options);
+                        wait = true;
+                    }
+                    break;
+                }
+            }
+            if (next == true && wait == false) {
+                this.forms[id].callback(this.forms[id].answers)
+                delete this.forms[id];
+            }
+            return false;
+        }
+    };
+
     this.broadcast = (filter, callback) => {
         if (!this.profiles_path) throw new Error("Profiles path is not defined");
         if (profiles.chats) {
@@ -460,11 +521,12 @@ function Bot(token, options) {
     this.init = () => {
         if (!this.token) throw new Error("Invalid token!");
         this.messageHandlers = [
+            this.handleForms,
             this.handleCommands,
             this.handleMessage
         ];
         if (this.profiles_path) {
-            this.messageHandlers.push(this.handleProfiles);
+            this.messageHandlers.unshift(this.handleProfiles);
             global.profiles = {users: {}, chats: {}};
             try {
                 global.profiles = require(this.profiles_path)

lib/Message.js

@@ -21,6 +21,7 @@ function Message(object, bot) {
     this.text_mentions = [];
     this.hashtags = [];
     this.links = [];
+    this.command = undefined;
     this.bot = bot;
 
     if (this.entities) {
@@ -41,6 +42,9 @@ function Message(object, bot) {
                         command = rawCommand.substr(0, index);
                     }
                     this.commands.push({command: command, recipient: recipient, args: args});
+                    if (offset === 0) {
+                        this.command = {command: command, recipient: recipient, args: args}
+                    }
                     break;
                 case 'mention':
                     this.mentions.push(text);