1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
Messaging
=========
Returning multiple responses
----------------------------
Often, with commands that take a long time to run, you may want to
be able to send some feedback to the user that the command is
progressing. Instead of using a single `return` statement you can
use `yield` statements for every line of output you wish to send to
the user.
In the following example, the output will be "Going to
sleep", followed by a 10 second wait period and "Waking up" in the end.
.. code-block:: python
from errbot import BotPlugin, botcmd
from time import sleep
class PluginExample(BotPlugin):
@botcmd
def longcompute(self, mess, args):
yield "Going to sleep"
sleep(10)
yield "Waking up"
Sending a message to a specific user or room
--------------------------------------------
Sometimes, you may wish to send a message to a specific user or a
groupchat, for example from pollers or on webhook events. You can do
this with :func:`~errbot.botplugin.BotPlugin.send`:
.. code-block:: python
self.send(
self.build_identifier("user@host.tld/resource"),
"Boo! Bet you weren't expecting me, were you?",
)
:func:`~errbot.botplugin.BotPlugin.send` requires a valid
:class:`~errbot.backends.base.Identifier` instance to send to.
:func:`~errbot.botplugin.BotPlugin.build_identifier`
can be used to build such an identifier.
The format(s) supported by `build_identifier` will differ depending on which backend you are using.
For example, on Slack it may support `#channel` and `@user`,
for XMPP it includes `user@host.tld/resource`, etc.
Templating
----------
It's possible to send `Markdown
<http://daringfireball.net/projects/markdown/>`_ responses using `Jinja2
<http://jinja.pocoo.org/>`_ templates.
To do this, first create a directory called *templates* in the
directory that also holds your plugin's *.plug* file.
Inside this directory, you can place Markdown templates (with a
*.md* extension) in place of the content you wish to show. For
example this *hello.md*:
.. code-block:: jinja
Hello, {{name}}!
.. note::
See the Jinja2 `Template Designer Documentation
<http://jinja.pocoo.org/docs/templates/>`_ for more information on
the available template syntax.
Next, tell Errbot which template to use by specifying the `template`
parameter to :func:`~errbot.decorators.botcmd` (leaving off the
*.md* suffix).
Finally, instead of returning a string, return a dictionary where
the keys refer to the variables you're substituting inside the
template (`{{name}}` in the above template example):
.. code-block:: python
from errbot import BotPlugin, botcmd
class Hello(BotPlugin):
@botcmd(template="hello")
def hello(self, msg, args):
"""Say hello to someone"""
return {'name': args}
It's also possible to use templates when using `self.send()`, but in
this case you will have to do the template rendering step yourself,
like so:
.. code-block:: python
from errbot import BotPlugin, botcmd
from errbot.templating import tenv
class Hello(BotPlugin):
@botcmd(template="hello")
def hello(self, msg, args):
"""Say hello to someone"""
response = tenv().get_template('hello.md').render(name=args)
self.send(msg.frm, response)
Cards
-----
Errbot cards are a canned format for notifications. It is possible to use this format to map to some native format in
backends like Slack (Attachment).
Similar to a `self.send()` you can use :func:`~errbot.botplugin.BotPlugin.send_card` to send a card.
The following code demonstrate the various available fields.
.. code-block:: python
from errbot import BotPlugin, botcmd
class Travel(BotPlugin):
@botcmd
def hello_card(self, msg, args):
"""Say a card in the chatroom."""
self.send_card(title='Title + Body',
body='text body to put in the card',
thumbnail='https://raw.githubusercontent.com/errbotio/errbot/master/docs/_static/errbot.png',
image='https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png',
link='http://www.google.com',
fields=(('First Key','Value1'), ('Second Key','Value2')),
color='red',
in_reply_to=msg)
Trigger a callback with every message received
----------------------------------------------
It's possible to add a callback that will be called on every message
sent either directly to the bot, or to a chatroom that the bot is
in:
.. code-block:: python
from errbot import BotPlugin
class PluginExample(BotPlugin):
def callback_message(self, mess):
if mess.body.find('cookie') != -1:
self.send(
mess.frm,
"What what somebody said cookie!?",
)
|
