docs: improve ActionCode to callback_data expanation

also add middleware to the examples which logs the called
callbackQuery.data in order to see whats happening.

see also #11

README.md

@@ -63,7 +63,7 @@ menu.simpleButton(text, action, {
 ```
 
 The second argument is the action.
-This has to be an unique identifier in the current menu and should stay the same as long as possible.
+This has to be an unique identifier in the current menu.
 It is used to determine the pressed button.
 Keep the action the same as long as possible over updates of the bot to ensure a smooth user experience as the user can continue seemlessly after bot restarts or updates.
 As it will be used as a part in the `callback_data` it should be short in order to allow more data in it.
@@ -75,6 +75,46 @@ This was used in the first line of the example to return the user `first_name`.
 As this is based on Telegraf see their [Docs](https://telegraf.js.org/) or [GitHub Repo](https://github.com/telegraf/telegraf).
 Also see the Telegram [Bot API Documentation](https://core.telegram.org/bots/api).
 
+## Action Code
+
+The Action Code identifies the specific button within the whole bot.
+It has to stay unique in order to know what specific button was pressed by the user.
+
+When using Telegraf for a callbackButton you would write something like this:
+```js
+bot.command('start', ctx => ctx.reply('Hi!', Markup.inlineKeyboard([
+  Markup.callbackButton('text', 'my-callback-data')
+])))
+
+bot.action('my-callback-data', ctx => ctx.answerCbQuery(''))
+```
+
+This library does the same for you.
+The `callback_data` is generated from the `action` parameters you supply.
+For example the following menu example will use `foo:bar:something` as `callback_data` for the `simpleButton`.
+
+```js
+const mainMenu = new TelegrafInlineMenu('Main Menu')
+const fooMenu = new TelegrafInlineMenu('Foo Menu')
+const barMenu = new TelegrafInlineMenu('Bar Menu')
+
+mainMenu.submenu('Open Foo Menu', 'foo', fooMenu)
+fooMenu.submenu('Open Bar Menu', 'bar', barMenu)
+barMenu.simpleButton('Hit me', 'something', {…})
+
+const bot = new Telegraf()
+bot.use(mainMenu.init())
+```
+
+Make sure the `action` argument is not too long.
+The current length of the `callback_data` can be [up to 64 bytes](https://core.telegram.org/bots/api#inlinekeyboardbutton).
+Especially take care of menu parts with dynamic content like `menu.select` or `menu.selectSubmenu` which tends to longer keys.
+
+(Advanced Usage:) Maybe you noted by now that the main menu has no action in the above example.
+The root menu actionCode can be set with `menu.init({actionCode: 'beep'})` and defaults to `main`.
+See `menu.init` docs for this.
+In order to save 5 bytes in the `callback_data` `main:` is ommited.
+
 ## Methods
 
 Methods generally support ES6 Promises as Parameters.

example.js

@@ -37,7 +37,7 @@ menu.select('s', ['A', 'B', 'C'], {
   isSetFunc: (_ctx, key) => key === selectedKey
 })
 
-const someMenu = new TelegrafInlineMenu('People like food. What do they like?')
+const foodMenu = new TelegrafInlineMenu('People like food. What do they like?')
 
 const people = {Mark: {}, Paul: {}}
 const food = ['bread', 'cake', 'bananas']
@@ -83,24 +83,24 @@ const foodSelectSubmenu = new TelegrafInlineMenu(foodSelectText)
     }
   })
 
-someMenu.selectSubmenu('p', () => Object.keys(people), foodSelectSubmenu, {
+foodMenu.selectSubmenu('p', () => Object.keys(people), foodSelectSubmenu, {
   textFunc: personButtonText,
   columns: 2
 })
 
-someMenu.question('Add person', 'add', {
+foodMenu.question('Add person', 'add', {
   questionText: 'Who likes food too?',
   setFunc: (_ctx, key) => {
     people[key] = {}
   }
 })
 
-menu.submenu('Food menu', 'b', someMenu, {
+menu.submenu('Food menu', 'food', foodMenu, {
   hide: () => mainMenuToggle
 })
 
 let isAndroid = true
-menu.submenu('Photo Menu', 'y', new TelegrafInlineMenu('', {
+menu.submenu('Photo Menu', 'photo', new TelegrafInlineMenu('', {
   photo: () => isAndroid ? 'https://telegram.org/img/SiteAndroid.jpg' : 'https://telegram.org/img/SiteiOs.jpg'
 }))
   .setCommand('photo')
@@ -120,6 +120,14 @@ const token = readFileSync('token.txt', 'utf8').trim()
 const bot = new Telegraf(token)
 bot.use(session())
 
+bot.use((ctx, next) => {
+  if (ctx.callbackQuery) {
+    console.log('another callbackQuery happened', ctx.callbackQuery.data.length, ctx.callbackQuery.data)
+  }
+
+  return next()
+})
+
 bot.use(menu.init({
   backButtonText: 'back…',
   mainMenuButtonText: 'back to main menu…'

example.ts

@@ -38,7 +38,7 @@ menu.select('s', ['A', 'B', 'C'], {
   isSetFunc: (_ctx, key) => key === selectedKey
 })
 
-const someMenu = new TelegrafInlineMenu('People like food. What do they like?')
+const foodMenu = new TelegrafInlineMenu('People like food. What do they like?')
 
 interface FoodChoises {
   food?: string;
@@ -89,24 +89,24 @@ const foodSelectSubmenu = new TelegrafInlineMenu(foodSelectText)
     }
   })
 
-someMenu.selectSubmenu('p', () => Object.keys(people), foodSelectSubmenu, {
+foodMenu.selectSubmenu('p', () => Object.keys(people), foodSelectSubmenu, {
   textFunc: personButtonText,
   columns: 2
 })
 
-someMenu.question('Add person', 'add', {
+foodMenu.question('Add person', 'add', {
   questionText: 'Who likes food too?',
   setFunc: (_ctx, key) => {
     people[key] = {}
   }
 })
 
-menu.submenu('Food menu', 'b', someMenu, {
+menu.submenu('Food menu', 'food', foodMenu, {
   hide: () => mainMenuToggle
 })
 
 let isAndroid = true
-menu.submenu('Photo Menu', 'y', new TelegrafInlineMenu('', {
+menu.submenu('Photo Menu', 'photo', new TelegrafInlineMenu('', {
   photo: () => isAndroid ? 'https://telegram.org/img/SiteAndroid.jpg' : 'https://telegram.org/img/SiteiOs.jpg'
 }))
   .setCommand('photo')
@@ -126,6 +126,14 @@ const token = readFileSync('token.txt', 'utf8').trim()
 const bot = new Telegraf(token)
 bot.use(session())
 
+bot.use((ctx, next) => {
+  if (ctx.callbackQuery && ctx.callbackQuery.data) {
+    console.log('another callbackQuery happened', ctx.callbackQuery.data.length, ctx.callbackQuery.data)
+  }
+
+  return next && next()
+})
+
 bot.use(menu.init({
   backButtonText: 'back…',
   mainMenuButtonText: 'back to main menu…'