| commit | author | age | ||
| 8bd4d9 | 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
| JK | 2 | <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="pl" lang="pl"> |
| 3 | <head> | |
| 4 | <title>Tworzenie modułów - Bot Gadu-Gadu - dev.Jacekk.info</title> | |
| 5 | <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=utf-8" /> | |
| 6 | <style type="text/css"> | |
| 7 | body {font-family: sans-serif;} | |
| 8 | h3 { padding: 5px 20px; | |
| 9 | border-top: 2px solid black; | |
| 10 | border-bottom: 2px solid black; | |
| 11 | text-transform: uppercase;} | |
| 12 | h3:before { | |
| 13 | counter-increment: header-h3; | |
| 14 | content: counter(header-h3) ". "; | |
| 15 | counter-reset: header-h4;} | |
| 16 | h4 { padding: 5px 10px; | |
| 17 | border-top: 1px solid black; | |
| 18 | border-bottom: 1px solid black;} | |
| 19 | h4:before { | |
| 20 | counter-increment: header-h4; | |
| 21 | content: counter(header-h4, lower-latin) ") ";} | |
| 22 | ol#menu ol {list-style-type: lower-latin;} | |
| 23 | pre { margin-left: 20px; | |
| 24 | border-left: 3px solid #666; | |
| 25 | padding-left: 12px;} | |
| 26 | pre.plain{border:none;} | |
| 27 | pre > span:first-child { | |
| 28 | display: block; | |
| 29 | background: #666; | |
| 30 | color: #fff; | |
| 31 | padding: 5px 10px; | |
| 32 | margin-left: -12px; | |
| 33 | margin-bottom: 8px;} | |
| 34 | code * {font-style: normal; | |
| 35 | font-weight: normal;} | |
| 36 | code var {color: #0000BB;} | |
| 37 | code b {color: #007700;} | |
| 38 | code cite {color: #DD0000;} | |
| 39 | code i {color: #FF9900;} | |
| 40 | .info, .warning, .example { | |
| 41 | padding-left: 40px; | |
| 42 | padding-top: 7px; | |
| 43 | min-height: 26px; | |
| 44 | background-repeat: no-repeat;} | |
| 45 | .info { background-image: url(img/info.png);} | |
| 46 | .warning {background-image: url(img/warning.png);} | |
| 47 | code, pre { | |
| 48 | margin-top:0px; | |
| 49 | padding-top:0;} | |
| 50 | .example { | |
| 51 | background-image: url(img/example.png); | |
| 52 | margin-bottom: 0px;} | |
| 53 | </style> | |
| 54 | </head> | |
| 55 | <body> | |
| 56 | <pre class="plain"> | |
| 57 | ___ ___ ______ _______ __ __ __ ___ ___ | |
| 58 | | \/ | / __ \ | __ \ | | | | | |__ \ \ / / | |
| 59 | | \ / | | | | | | | \ | | | | | | ' / \ \/ / | |
| 60 | | |\/| | | | | | | | | | | | | | | / \ / | |
| 61 | | | | | | |__| | | |__/ | | |__| | | |____ | | | |
| 62 | |__| |__| \______/ |_______/ \______/ |_______| |__| | |
| 6f84c6 | 63 | Poradnik v2.1 Tworzenie i edycja |
| 8bd4d9 | 64 | </pre> |
| JK | 65 | |
| 66 | <h3 id="tableOfContent">Spis treści</h3> | |
| 67 | ||
| 68 | <div id="menu"> | |
| 69 | </div> | |
| 70 | ||
| 71 | <h3 id="interfaceBotModuleInit">Rejestracja modułu - interfejs BotModuleInit</h3> | |
| 72 | ||
| 73 | <p>Należy w katalogu ./modules/ utworzyć folder o dowolnej nazwie, na przykład:</p> | |
| 74 | <pre>99_NAZWAMODULU</pre> | |
| 75 | ||
| 76 | <p class="info">Zaleca się, by nazwa folderu była postaci 00_NAZWAMODULU, gdzie 00 to cyfry umożliwiające ustawienie kolejności modułów. Jest to przydatne przy wyświetlaniu pomocy lub listy funkcji.</p> | |
| 77 | ||
| 78 | <p>Folder ten powinien zawierać plik o nazwie init.php, zawierający klasę o dowolnej nazwie, implementującą BotModuleInit, oraz co najmniej dwie metody - register i help. Na końcu pliku powinna znajdować się konstrukcja return, zwracająca nazwę klasy:</p> | |
| 79 | ||
| 80 | <pre> | |
| 81 | <span>./modules/99_NAZWAMODULU/init.php</span><code><b><?php | |
| 82 | class <var>bot_NAZWAMODULU_init</var> implements <a href="#interfaceBotModuleInit"><var>BotModuleInit</var></a> | |
| 83 | { | |
| 84 | function <var>register</var>() { | |
| 85 | } | |
| 86 | ||
| 87 | function <var>help</var>(<var>$params</var> = NULL) { | |
| 88 | } | |
| 89 | } | |
| 90 | ||
| 91 | return <cite>'bot_NAZWAMODULU_init'</cite>; | |
| 92 | ?></b></code> | |
| 93 | </pre> | |
| 94 | ||
| 95 | <p class="info">By nie powodować konfliktów nazw, zaleca się, by nazwa klasy była formatu bot_NAZWAMODULU_init, jednak nie jest to wymagane.</p> | |
| 96 | <p class="warning">Błąd składniowy w pliku init.php może powodować błędy w działaniu całego bota!</p> | |
| 97 | <p class="warning">Informacje zwracane przez plik inicjujący są cache'owane. Po każdej zmianie pliku init.php należy koniecznie usunąć zawartość folderu cache!</p> | |
| 98 | ||
| 99 | <h4 id="interfaceBotModuleInit_methodRegister">Metoda register()</h4> | |
| 100 | ||
| 101 | <p>Metoda <code><var>register</var><b>()</b></code> ma zwracać tablicę następującej postaci:</p> | |
| 102 | <pre> | |
| 103 | <code><b>array(</b> | |
| 104 | <cite>'komenda' <b>=> array( | |
| 105 | array(</b> | |
| 106 | 'file' <b>=></b> 'komenda.php'<b>,</b> | |
| 107 | 'class' <b>=></b> 'bot_NAZWAMODULU_module'<b>,</b> | |
| 108 | 'method' <b>=></b> 'komenda1'<b>,</b> | |
| 109 | 'params' <b>=></b> 'parametr_do_funkcji'<b>, | |
| 110 | ), | |
| 111 | array(</b> | |
| 112 | 'file' <b>=></b> 'komenda.php'<b>,</b> | |
| 113 | 'class' <b>=></b> 'bot_NAZWAMODULU_module'<b>,</b> | |
| 114 | 'method' <b>=></b> 'komenda2'<b>, | |
| 115 | ), | |
| 116 | ),</b> | |
| 117 | '*'<b> => array( | |
| 118 | array(</b> | |
| 119 | 'file' <b>=></b> 'test.php'<b>,</b> | |
| 120 | 'class' <b>=></b> 'NAZWAMODULU_test'<b>,</b> | |
| 121 | 'method' <b>=></b> 'komenda_test'</cite><b>, | |
| 122 | ), | |
| 123 | ), | |
| 124 | )</b></code> | |
| 125 | </pre> | |
| 126 | ||
| 127 | <p><code><cite>'komenda'</cite></code> to nazwa obsługiwanej przez moduł komendy. <code><cite>'*'</cite></code> oznacza, że obsługiwana może być każda wiadomość od użytkownika. <code><cite>'file'</cite></code> zawiera nazwę pliku, w którym znajduje się klasa z parametru <code><cite>'class'</cite></code>. <code><cite>'method'</cite></code> to metoda klasy, która przetwarza daną komendę. Opcjonalny parametr <code><cite>'params'</cite></code> zawiera dowolny obiekt (np. string, array), na którym można wykonać funkcję <code><a href="http://php.net/serialize"><var>serialize</var></a><b>()</b></code>, a który zostanie przekazany do wywoływanej metody. Więcej informacji o sposobie przetwarzania wiadomości od użytkownika znajduje się w kolejnym dziale: <a href="#interfaceBotModule">Komunikacja z użytkownikiem - interfejs BotModule</a></p> | |
| 128 | ||
| 129 | <p class="info"><code><cite>'komenda'</cite></code> powinna zawierać jedynie małe litery alfabetu angielskiego. Jeżeli zawiera polskie ogonki lub wielkie litery, zostaną one automatycznie zastąpione odpowiednikami. Jeśli równocześnie istnieją indeksy zawierające np. <code><cite>'ą'</cite></code> oraz <code><cite>'a'</cite></code>, mogą one zostać połączone w dowolnej kolejności.</p> | |
| 130 | ||
| 131 | <p class="example">Przykład - rejestrowanie komendy przyklad:</p> | |
| 132 | <pre> | |
| 133 | <span>./modules/99_przyklad/init.php</span><code><b><?php | |
| 134 | class <var>bot_przyklad_init</var> implements <a href="#interfaceBotModuleInit"><var>BotModuleInit</var></a> | |
| 135 | { | |
| 136 | function <var>register</var>() { | |
| 137 | return array(</b> | |
| 138 | <cite>'przyklad' <b>=> array( | |
| 139 | array(</b> | |
| 140 | 'file' <b>=></b> 'przyklad.php'<b>,</b> | |
| 141 | 'class' <b>=></b> 'bot_przyklad_module'<b>,</b> | |
| 142 | 'method' <b>=></b> 'komenda_przyklad'<b>,</b> | |
| 143 | 'params' <b>=></b> 'parametr_do_funkcji'</cite><b>, | |
| 144 | ) | |
| 145 | ) | |
| 146 | ); | |
| 147 | } | |
| 148 | ||
| 149 | <i>/* Pominięto tu wymaganą metodę help(). | |
| 150 | Jej implementację można znaleźć poniżej. */</i> | |
| 151 | } | |
| 152 | ||
| 153 | return <cite>'bot_przyklad_init'</cite>; | |
| 154 | ?></b></code> | |
| 155 | </pre> | |
| 156 | ||
| 157 | <p class="info">W dalszej części zakładamy, że tworzymy moduł obsługujący komendę przyklad.</p> | |
| 158 | ||
| 159 | <h4 id="interfaceBotModuleInit_methodHelp">Metoda help()</h4> | |
| 160 | ||
| 161 | <p>Metoda <code><var>help</var><b>()</b></code> przyjmuje argument <code><var>$params</var></code> - nazwę komendy, dla której ma zwrócić, za pośrednictwem <a href="classBotMsg">klasy BotMsg</a>, pomoc. Jeśli argument ten jest identyczny z <code><b>NULL</b></code>, należy zwrócić skróconą listę poleceń z krótkim wyjaśnieniem, zakończoną dwoma znakami nowej linii.</p> | |
| 162 | ||
| 163 | <p>Jeżeli moduł nie ma pomocy lub nie obsługuje danej komendy (szczególnie dla pseudokomendy <code><cite>'*'</cite></code>), powinna zostać zwrócona wartość <code><b>FALSE</b></code></p> | |
| 164 | ||
| 165 | <p>Jeżeli żaden moduł nie zwrócił wiadomości z pomocą, użytkownik jest informowany o braku pomocy dla danej komendy.</p> | |
| 166 | ||
| 167 | <p class="info">Skrócona lista poleceń jest generowana tylko z tych plików init.php, które rejestrują przynajmniej jedną komendę.</p> | |
| 168 | ||
| 169 | <p class="example">Przykład - funkcja <code><var>help</var><b>()</b></code>:</p> | |
| 170 | <pre> | |
| 171 | <code><b> function <var>help</var>(<var>$params</var> = NULL) { | |
| 172 | if(<var>$params</var> === NULL) { | |
| 173 | return new <a href="#classBotMsg"><var>BotMsg</var></a>(<cite>'<b>przyklad</b> <i>[argument]</i><br />'<b>.</b>"\n"<b>.</b> | |
| 174 | ' Zwraca przykładowy tekst oraz treść argumentu<br /><br />'</cite>); | |
| 175 | } | |
| 176 | else | |
| 177 | { | |
| 178 | return new <a href="#classBotMsg"><var>BotMsg</var></a>(<cite>'<b>przyklad</b> <i>[argument]</i><br />'<b>.</b>"\n"<b>.</b> | |
| 179 | ' Komenda zwraca przykładowy tekst oraz treść argumentu <i>[argument]</i> (jeśli istnieje)'</cite>); | |
| 180 | } | |
| 181 | }</b></code> | |
| 182 | </pre> | |
| 183 | ||
| 184 | <h4 id="interfaceBotModuleInit_example">Przykład</h4> | |
| 185 | <pre> | |
| 186 | <span>./modules/99_przyklad/init.php</span><code><b><?php | |
| 187 | class <var>bot_przyklad_init</var> implements <var>BotModuleInit</var> | |
| 188 | { | |
| 189 | function <var>register</var>() { | |
| 190 | return array(</b> | |
| 191 | <cite>'przyklad' <b>=> array( | |
| 192 | array(</b> | |
| 193 | 'file' <b>=></b> 'przyklad.php'<b>,</b> | |
| 194 | 'class' <b>=></b> 'bot_przyklad_module'<b>,</b> | |
| 195 | 'method' <b>=></b> 'komenda_przyklad'<b>,</b> | |
| 196 | 'params' <b>=></b> 'parametr_do_funkcji'</cite><b>, | |
| 197 | ) | |
| 198 | ) | |
| 199 | ); | |
| 200 | } | |
| 201 | ||
| 202 | function <var>help</var>(<var>$params</var> = NULL) { | |
| 203 | if(<var>$params</var> === NULL) { | |
| 204 | return new <a href="#classBotMsg"><var>BotMsg</var></a>(<cite>'przyklad <i>[argument]</i><br />'<b>.</b>"\n"<b>.</b> | |
| 205 | ' Zwraca przykładowy test oraz treść argumentu<br /><br />'</cite>); | |
| 206 | } | |
| 207 | else | |
| 208 | { | |
| 209 | return new <a href="#classBotMsg"><var>BotMsg</var></a>(<cite>'przyklad <i>[argument]</i><br />'<b>.</b>"\n"<b>.</b> | |
| 210 | ' Komenda zwraca przykładowy test oraz treść argumentu <i>[argument]</i> (jeśli istnieje)'</cite>); | |
| 211 | } | |
| 212 | } | |
| 213 | } | |
| 214 | ||
| 215 | return <cite>'bot_przyklad_init'</cite>; | |
| 216 | ?></b></code> | |
| 217 | </pre> | |
| 218 | ||
| 219 | <h4 id="interfaceBotModuleInit_more">Dalsze informacje</h4> | |
| 220 | ||
| 221 | <p>Następne sekcje zawierają informacje dotyczące klas i metod, które umożliwiają przetwarzanie wiadomości od użytkownika i wysyłanie komunikatu zwrotnego.</p> | |
| 222 | ||
| 223 | <p class="info">Jeśli moduł posiada dane, które musi przechowywać (np. słownik, tabelę kursów itp.), należy zapoznać się z sekcją <a href="#appendixDataStorage">Przechowywanie danych i ich aktualizacja</a></p> | |
| 224 | ||
| 225 | <h3 id="classBotMessage">Informacje o użytkowniku i treść wiadomości - klasa BotMessage</h3> | |
| 226 | ||
| 227 | <p>Wszystkie informacje związane z użytkownikiem są przekazywane jako pierwszy parametr do metody zarejestrowanej komendy pod postacią klasy potomnej BotMessage. Zawiera ona nastepujące pola:</p> | |
| 228 | ||
| 229 | <h4 id="classBotMessage_propertyUser">Pole $user</h4> | |
| 230 | ||
| 231 | <p>Zawiera wszystkie informacje o źródle i celu wiadomości - w postaci klasy BotUser. Zakładając, że <code><var>$msg</var></code> to nazwa zmiennej zawierającej klasę BotMessage, można uzyskać następujące informacje:</p> | |
| 232 | ||
| 233 | <pre> | |
| 234 | <code><var>$msg<b>-></b>user<b>-></b>interface</var></code> | |
| 235 | </pre> | |
| 236 | ||
| 237 | <p>Zawiera tekst: <code><cite>'Gadu-Gadu'</cite></code>, <code><cite>'IMified'</cite></code>, <code><cite>'HTTP'</cite></code> lub inny, który określa źródło wiadomości</p> | |
| 238 | ||
| 239 | <pre> | |
| 240 | <code><var>$msg<b>-></b>user<b>-></b>uid</var></code> | |
| 241 | </pre> | |
| 242 | ||
| 243 | <p>Zawiera numer użytkownika lub jego identyfikator (screen name).</p> | |
| 244 | ||
| 245 | <pre> | |
| 246 | <code><var>$msg<b>-></b>user<b>-></b>network</var></code> | |
| 247 | </pre> | |
| 248 | ||
| 249 | <p>Jeden z ciągów: <code><cite>'gadu-gadu.pl'</cite></code>, <code><cite>'jabber.imified.com'</cite></code>, <code><cite>'aim.imified.com'</cite></code>, <code><cite>'msn.imified.com'</cite></code>, <code><cite>'yahoo.imified.com'</cite></code>, <code><cite>'gtalk.imified.com'</cite></code>, <code><cite>'sms.imified.com'</cite></code> lub inny, identyfikujący sieć użytkownika.</p> | |
| 250 | ||
| 251 | <pre> | |
| 252 | <code><var>$msg<b>-></b>user<b>-></b>bot</var></code> | |
| 253 | </pre> | |
| 254 | ||
| 255 | <p>Informacja o bocie, do którego została wysłana wiadomość. Numer w przypadku Gadu-Gadu lub botkey w przypadku IMified.</p> | |
| 256 | ||
| 257 | <pre> | |
| 258 | <code><var>$msg<b>-></b>user<b>-></b>params</var></code> | |
| 259 | </pre> | |
| 260 | ||
| 261 | <p>Inne parametry. W przypadku IMified zawiera ciąg <code><cite>'public'</cite></code> lub <code><cite>'private'</cite></code>, pozwalający odróżnić źródło wiadomości na twitterze.</p> | |
| 262 | ||
| 263 | <h4 id="classBotMessage_propertySession">Pole $session</h4> | |
| 264 | ||
| 265 | <p>Odpowiednik klasy database z poprzedniej wersji bota. Aktualnie instancja klasy BotSession, umożliająca przechowywanie danych przypisanych do użytkownika, m.in. miasta, nazwy kina i tym podobnych.</p> | |
| 266 | ||
| 267 | <p>Przykład użycia:</p> | |
| 268 | ||
| 269 | <pre> | |
| 270 | <code><i>// Ustawienie pojedynczej wartości</i> | |
| 271 | <var>$msg<b>-></b>session<b>-></b>zmienna</var> <b>= <cite>'To jest test'</cite>;</b> | |
| 272 | <a href="http://php.net/assert"><b>assert</b></a><b>(</b><var>$msg<b>-></b>session<b>-></b>zmienna</var> <b>=== <cite>'To jest test'</cite>);</b> | |
| 273 | ||
| 274 | <i>// Usunięcie pojedynczej wartości</i> | |
| 275 | <a href="http://php.net/unset"><b>unset</b></a><b>(</b><var>$msg<b>-></b>session<b>-></b>zmienna</var><b>);</b> | |
| 276 | <a href="http://php.net/assert"><b>assert</b></a><b>(</b><var>$msg<b>-></b>session<b>-></b>zmienna</var> <b>=== NULL);</b> | |
| 277 | ||
| 278 | <i>// Usunięcie wszystkich danych</i> | |
| 279 | <var>$msg<b>-></b>session<b>-></b>truncate</var><b>();</b> | |
| 280 | <a href="http://php.net/assert"><b>assert</b></a><b>(</b><var>$msg<b>-></b>session<b>-></b>zmienna</var> <b>=== NULL);</b> | |
| 281 | ||
| 282 | <i>// Dopisanie (nadpisanie) danych</i> | |
| 283 | <var>$tablica</var> <b>= array(</b> | |
| 284 | <cite>'zmienna' <b>=></b> 'To jest test'<b>,</b> | |
| 285 | 'zmienna2'</cite> <b>=> new DateTime() | |
| 286 | );</b> | |
| 287 | <var>$msg<b>-></b>session<b>-></b>push<b>(</b>$tablica</var><b>);</b> | |
| 288 | ||
| 289 | <a href="http://php.net/assert"><b>assert</b></a><b>(</b><var>$msg<b>-></b>session<b>-></b>zmienna</var> <b>=== <cite>'To jest test'</cite>);</b> | |
| 290 | <a href="http://php.net/assert"><b>assert</b></a><b>(</b><var>$msg<b>-></b>session<b>-></b>pull<b>() ===</b> $tablica</var><b>);</b> | |
| 291 | ||
| 292 | <i>// push() nie usuwa istniejących danych</i> | |
| 293 | <var>$msg<b>-></b>session<b>-></b>zmienna3</var> <b>= <cite>'To jest test'</cite>;</b> | |
| 294 | <var>$msg<b>-></b>session<b>-></b>push<b>(</b>$tablica</var><b>);</b> | |
| 295 | <a href="http://php.net/assert"><b>assert</b></a><b>(</b><var>$msg<b>-></b>session<b>-></b>pull<b>() !==</b> $tablica</var><b>);</b> | |
| 296 | ||
| 297 | <i>// Usunięcie wszystkich danych</i> | |
| 298 | <var>$msg<b>-></b>session</var><b>->truncate();</b> | |
| 299 | <a href="http://php.net/assert"><b>assert</b></a><b>(</b><var>$msg<b>-></b>session<b>-></b>zmienna</var> <b>=== NULL);</b></code> | |
| 300 | </pre> | |
| 301 | ||
| 302 | <h4 id="classBotMessage_propertyRawText">Pole $rawText</h4> | |
| 303 | ||
| 304 | <p>Zawiera dane, które zostały otrzymane od API, bez żadnych zmian, z zachowanym oryginalnym formatowaniem.</p> | |
| 305 | ||
| 306 | <pre> | |
| 307 | <code><var>$msg<b>-></b>rawText</var></code> | |
| 308 | </pre> | |
| 309 | ||
| 310 | <h4 id="classBotMessage_propertyText">Pole $text</h4> | |
| 311 | ||
| 312 | <p>Zawiera dane, które zostały otrzymane od API, wielkie litery zamienione na małe, wszystkie znaki alfabetu innego niż angielski transliterowane. Zobacz: <code><var>funcs</var><b>::</b><a href="#appendixHelpers_classFuncs_methodUtfToAscii"><var>utfToAscii</var></a><b>()</b></code></p> | |
| 313 | ||
| 314 | <pre> | |
| 315 | <code><var>$msg<b>-></b>text</var></code> | |
| 316 | </pre> | |
| 317 | ||
| 318 | <h4 id="classBotMessage_propertyCommand">Pole $command</h4> | |
| 319 | ||
| 320 | <p>Nazwa komendy (pierwszy wyraz z <a href="#classBotMessage_propertyText">pola $text</a>).</p> | |
| 321 | ||
| 322 | <pre> | |
| 323 | <code><var>$msg<b>-></b>command</var></code> | |
| 324 | </pre> | |
| 325 | ||
| 326 | <h4 id="classBotMessage_propertyArgs">Pole $args</h4> | |
| 327 | ||
| 328 | <p>Parametry przekazane do komendy (pozostałe wyrazy z <a href="#classBotMessage_propertyRawText">pola $rawText</a>).</p> | |
| 329 | ||
| 330 | <pre> | |
| 331 | <code><var>$msg<b>-></b>args</var></code> | |
| 332 | </pre> | |
| 333 | ||
| 6f84c6 | 334 | <h4 id="classBotMessage_propertyImages">Pole $images</h4> |
| JK | 335 | |
| 336 | <p>Tablica obrazków (obiektów klasy BotImage) przesłanych do bota przez użytkownika.</p> | |
| 337 | ||
| 338 | <pre> | |
| 339 | <code><b>if(<a href="http://php.net/assert"><var>count</var></a>(<var>$msg</var>-><var>images</var>) > <var>0</var>) {</b> | |
| 340 | <i>// Do bota zostały przesłane obrazki</i> | |
| 341 | ||
| 342 | <i>// Pierwszy obrazek</i> | |
| 343 | <var>$img <b>=</b> $msg<b>-></b>images</var><b>[<var>0</var>];</b> | |
| 344 | ||
| 345 | <i>// Obrazek w formie gotowej do obróbki za pomocą biblioteki GD</i> | |
| 346 | <var>$gd <b>=</b> $img<b>-></b>getImage</var><b>();</b> | |
| 347 | <a href="http://php.net/imagestring"><var>imagestring</var></a><b>(</b><var>$gd<b>,</b> 2<b>,</b> 0<b>,</b> 0</var><b>, <cite>'To jest tekst'</cite>,</b> <a href="http://php.net/imagecolorallocate"><var>imagecolorallocate</var></a><b>(<var>$gd<b>,</b> 255<b>,</b> 255<b>,</b> 255</var>));</b> | |
| 348 | ||
| 349 | <i>// Obrazek jako ciąg bajtów gotowych do zapisu:</i> | |
| 350 | <var>$data <b>=</b> $img<b>-></b>getImageData</var><b>();</b> | |
| 351 | <a href="http://php.net/file_put_contents"><var>file_put_contents</var></a><b>(<cite>'/tmp/obrazek.jpg'</cite>, <var>$data</var>);</b> | |
| 352 | <b>}</b></code> | |
| 353 | </pre> | |
| 354 | ||
| 8bd4d9 | 355 | <h3 id="interfaceBotModule">Komunikacja z użytkownikiem - interfejs BotModule</h3> |
| JK | 356 | |
| 357 | <p>Zgodnie z danymi zwracanymi przez <a href="#interfaceBotModuleInit_methodRegister">metodę register</a>, należy utworzyć plik zawierający klasę o podanej nazwie, implementującą BotModule, oraz odpowiednią metodę, przyjmującą dwa parametry:</p> | |
| 358 | ||
| 359 | <pre> | |
| 360 | <code><b><?php | |
| 361 | class <var>bot_przyklad_module</var> implements <a href="#interfaceBotModule"><var>BotModule</var></a> | |
| 362 | { | |
| 363 | function <var>komenda_przyklad</var>(<var>$msg</var>, <var>$param</var> = NULL) { | |
| 364 | } | |
| 365 | }</b></code> | |
| 366 | </pre> | |
| 367 | ||
| 368 | <p>Po wysłaniu przez użytkownika do bota polecenia, system wywoła w kolejności moduły, które zarejestrowały otrzymaną komendę (pierwszy wyraz w wiadomości), a następnie spróbuje wykonać moduły, które zarejestrowały się jako właściwe dla wszytkich komend (indeksem tablicy zwróconej w metodzie register była <code><cite>'*'</cite></code>). Do metod zostaną przekazane dwa parametry, opisane w powyższym przykładzie jako <code><var>$msg</var></code> i <code><var>$param</var></code>. Pierwszy z nich to instancja klasa <a href="#classBotMessage">BotMessage</a>, a drugi - wartość z indeksu <code><cite>'params'</cite></code> podawanego podczas rejestracji komendy.</p> | |
| 369 | ||
| 370 | <p>Wywołana metoda powinna zwrócić instancję <a href="#classBotMsg">klasy BotMsg</a> lub <code><b>FALSE</b></code>, jeżeli nie chce obsłużyć otrzymanej wiadomości. W drugim przypadku obsługa zostanie przekazana kolejnej metodzie/modułowi, który zarejestrował daną komendę, następnie do plików obsługujących komendę "*", a na końcu użytkownikowi zostanie wysłana informacja o nieobsługiwanym poleceniu.</p> | |
| 371 | ||
| 372 | <p class="info">Jeśli moduł ma przechowywać dane dotyczące użytkownika, należy zapoznać się z sekcją <a href="#classBotMessage_propertySession">Klasa BotMessage - pole $session</a></p> | |
| 373 | ||
| 374 | <pre> | |
| 375 | <span>./modules/99_przyklad/przyklad.php</span><code><b><?php | |
| 376 | class <var>bot_przyklad_module</var> implements <a href="#interfaceBotModule"><var>BotModule</var></a> | |
| 377 | { | |
| 378 | function <var>komenda_przyklad</var>(<var>$msg</var>, <var>$param</var> = NULL) {</b> | |
| 379 | <var>$reply</var> <b>= new</b> <a href="#classBotMsg"><var>BotMsg</var></a><b>(<cite>'<p>Przykładowy moduł</p>'</cite>);</b> | |
| 380 | <var>$reply</var><b>-></b><a href="#classBotMsg_methodAppend"><var>append</var></a><b>(<cite>'<p>Twój numer/identyfikator: '</cite> .</b> <var>$msg</var><b>-></b><a href="#classBotMessage_propertyUser"><var>user</var></a><b>-></b><var>uid</var> <b>. <cite>'<br />'</cite> | |
| 381 | . <cite>'Otrzymane parametry: '</cite> .</b> <var>$msg</var><b>-></b><a href="#classBotMessage_propertyArgs"><var>args</var></a> <b>. <cite>'</p>'</cite>); | |
| 382 | return <var>$reply</var>; | |
| 383 | } | |
| 384 | } | |
| 385 | ?></b></code> | |
| 386 | </pre> | |
| 387 | ||
| 388 | <h3 id="classBotMsg">Tworzenie wiadomości zwrotnej - klasa BotMsg</h3> | |
| 389 | ||
| 390 | <p>Aby utworzyć wiadomość dla użytkownika, należy stworzyć instację klasy BotMsg, która jako opcjonalny parametr przyjmuje kod HTML, który ma zostać wysłany użytkownikowi:</p> | |
| 391 | ||
| 392 | <pre> | |
| 393 | <code><var>$reply</var> <b>= new</b> <a href="#classBotMsg"><var>BotMsg</var></a><b>();</b> | |
| 394 | <i>// lub</i> | |
| 395 | <var>$reply</var> <b>= new</b> <a href="#classBotMsg"><var>BotMsg</var></a><b>(<cite>'<p>Akapit z tekstem <b>pogrubionym</b> i <i>pochylonym</i></p>'</cite>);</b></code> | |
| 396 | </pre> | |
| 397 | ||
| 398 | <p class="info">W wiadomości przekonwertowanej na tekst <b>zachowywane są białe znaki</b>, za wyjątkiem znaków nowej linii!</p> | |
| 399 | ||
| 400 | <h4 id="classBotMsg_methodAppend">Metoda append()</h4> | |
| 401 | ||
| 402 | <p>W razie konieczności dodania większej ilości treści, należy wywołać metodę <code><var>append</var><b>()</b></code> lub <code><var>a</var><b>()</b></code> z parametrem będącym kodem HTML:</p> | |
| 403 | ||
| 404 | <pre> | |
| 405 | <code><var>$reply</var> <b>= new</b> <a href="#classBotMsg"><var>BotMsg</var></a><b>();</b> | |
| 406 | ||
| 407 | <var>$reply</var><b>-></b><a href="#classBotMsg_methodAppend"><var>a</var></a><b>(<cite>'<ol> | |
| 408 | <li>pierwszy element listy</li> | |
| 409 | <li>drugi element listy</li> | |
| 410 | </ol>'</cite>);</b> | |
| 411 | ||
| 412 | <var>$reply</var><b>-></b><a href="#classBotMsg_methodAppend"><var>append</var></a><b>(<cite>'<p>Kolejny akapit</p>'</cite>);</b></code> | |
| 413 | </pre> | |
| 414 | ||
| 415 | <p class="warning">Zaleca się, by dodawany kod nie był "urwany", tzn. wszystkie tagi winny być poprawnie otwarte i zamknięte we wstawianym HTML-u. W przyszłości takie błędy mogą powodować odrzucenie dodawanej treści.</p> | |
| 416 | ||
| 417 | <h4 id="classBotMsg_appendixImage">Dodawanie obrazków</h4> | |
| 418 | ||
| 419 | <p>Aby dodać obrazek należy do kodu HTML dodać tag img, z atrybutem src zawierającym ścieżkę do obrazka względem głównego katalogu bota lub bezwzględną ścieżkę dostępu do niego:</p> | |
| 420 | ||
| 421 | <pre> | |
| 422 | <code><var>$reply</var><b>-></b><a href="#classBotMsg_methodAppend"><var>a</var></a><b>(<cite>'<p>Tu będzie obrazek: <img src="data/przyklad/obrazek.png" /></p>'</cite>);</b></code> | |
| 423 | </pre> | |
| 424 | ||
| 425 | <p class="warning">Gadu-Gadu nie obsługuje więcej niż jednego obrazka w wiadomości.</p> | |
| 426 | ||
| 427 | <h4 id="classBotMsg_appendixTags">Wspierane tagi HTML</h4> | |
| 428 | ||
| 429 | <p>Wspierane tagi HTML:</p> | |
| 430 | ||
| 431 | <ul> | |
| 432 | <li>a (tylko atrybut href)</li> | |
| 433 | <li>b</li> | |
| 434 | <li>br</li> | |
| 435 | <li>h1</li> | |
| 436 | <li>h2</li> | |
| 437 | <li>h3</li> | |
| 438 | <li>i</li> | |
| 439 | <li>img (tylko atrybut src)</li> | |
| 440 | <li>li</li> | |
| 441 | <li>ol (także atrybut start)</li> | |
| 442 | <li>p</li> | |
| 443 | <li>span</li> | |
| 444 | <li>strong</li> | |
| 445 | <li>sub</li> | |
| 446 | <li>sup</li> | |
| 447 | <li>u</li> | |
| 448 | <li>ul</li> | |
| 449 | </ul> | |
| 450 | ||
| 451 | <p>Wspierane atrybuty:</p> | |
| 452 | ||
| 453 | <ul> | |
| 454 | <li>color (tylko w formacie: #ABC lub #AABBCC)</li> | |
| 455 | <li>style</li> | |
| 456 | </ul> | |
| 457 | ||
| 458 | <h3 id="appendixHelpers">Funkcje pomocnicze</h3> | |
| 459 | ||
| 460 | <p>Poniższe klasy zawierają funkcje często używane w modułach.</p> | |
| 461 | ||
| 462 | <h4 id="appendixHelpers_classCalendar_methodParseDate">calendar::parse_date()</h4> | |
| 463 | ||
| 464 | <p>Metoda <code><var>parse_date</var></code> klasy <code><var>calendar</var></code> jest zdefiniowana następująco:</p> | |
| 465 | ||
| 466 | <pre> | |
| 467 | <code><b>static function</b> <a href="#appendixHelpers_classCalendar_methodParseDate"><var>parse_date</var></a><b>(</b><var>$date</var><b>);</b></code> | |
| 468 | </pre> | |
| 469 | ||
| 470 | <p>Przetwarza ona tekst <code><var>$date</var></code> (np. <code><cite>'wczoraj'</cite></code>, <code><cite>'jutro'</cite></code>, ale także <code><cite>'1 stycznia 2000'</cite></code>) na uniksowy znacznik czasu, który zwraca.</p> | |
| 471 | ||
| 472 | <p class="example">Przykład:</p> | |
| 473 | <pre> | |
| 474 | <code><var>$data</var> <b>=</b> <a href="#appendixHelpers_classCalendar_methodParseDate"><var>calendar</var><b>::</b><var>parse_date</var></a><b>(</b><cite>'29 stycznia 2009'</cite><b>);</b> | |
| 475 | <var>$wzor</var> <b>=</b> <a href="http://php.net/mktime"><var>mktime</var></a><b>(</b><var>0</var><b>,</b> <var>0</var><b>,</b> <var>0</var><b>,</b> <var>1</var><b>,</b> <var>29</var><b>,</b> <var>2009</var><b>);</b> | |
| 476 | <a href="http://php.net/assert"><b>assert</b></a><b>(</b><var>$data</var> <b>==</b> <var>$wzor</var><b>);</b></code> | |
| 477 | </pre> | |
| 478 | ||
| 479 | <h4 id="appendixHelpers_classFuncs_methodUtfToAscii">funcs::utfToAscii()</h4> | |
| 480 | ||
| 481 | <p>Metoda <code><var>utfToAscii</var></code> klasy <code><var>funcs</var></code> jest zdefiniowana następująco:</p> | |
| 482 | ||
| 483 | <pre> | |
| 484 | <code><b>static function</b> <a href="#appendixHelpers_classFuncs_methodUtfToAscii"><var>utfToAscii</var></a><b>(</b><var>$utf</var><b>);</b></code> | |
| 485 | </pre> | |
| 486 | ||
| 487 | <p>Polskie znaki w zmiennej <code><var>$utf</var></code> zamienia w litery alfabetu angielskiego (ó => o, ź => z itd.), wykonuje na tekście <code><a href="http://php.net/strtolower"><var>strtolower</var></a><b>()</b></code> oraz <code><a href="http://php.net/trim"><var>trim</var></a><b>()</b></code>, po czym zwraca tak zmodyfikowaną treść.</p> | |
| 488 | ||
| 489 | <h3 id="appendixDataStorage">Przechowywanie danych i ich aktualizacja</h3> | |
| 490 | ||
| 491 | <p>Jeśli istnieje potrzeba okresowego aktualizowania danych (np. kursów walut) można użyć do tego przygotowanego specjalnie dla tego bota narzędzia.</p> | |
| 492 | ||
| 493 | <p>W folderze /data/(nazwa modułu)/ należy utworzyć plik crontab, zgodny ze <a href="http://pl.wikipedia.org/wiki/Crontab">składnią crontaba</a>.</p> | |
| 494 | ||
| 495 | <p class="example">Przykład pliku crontab:</p> | |
| 496 | <pre> | |
| 497 | <code><i># To jest komentarz - znak # musi być pierwszym znakiem w linijce! | |
| 498 | ||
| 499 | # Uruchamiaj się codziennie, co dwie godziny, między północą a dwudziestą.</i> | |
| 500 | <var>0 0</var><b>-</b><var>20</var><b>/</b><var>2</var> <b>* * *</b> <cite>co_dwie_godziny.php</cite> | |
| 501 | <i># Uruchamiaj się o 4:00 w każdą niedzielę</i> | |
| 502 | <var>0 4</var> <b>* *</b> <var>0</var> <cite>niedziela.php</cite> | |
| 503 | <i># Uruchamiaj się w każdy poniedziałek i środę o 10:00</i> | |
| 504 | <var>0 10</var> <b>* *</b> <var>1</var><b>,</b><var>3</var> <cite>pon_sr_10.php</cite></code> | |
| 505 | </pre> | |
| 506 | ||
| 507 | <p class="warning"> Pierwsze pole (minuty) jest pomijane, tj. nie można uruchamiać programu częsciej niż raz na godzinę!</p> | |
| 508 | <p class="warning"> W pole 6 należy, zamiast pełnej komendy, wpisać jednynie nazwę pliku z rozszerzeniem .php, znajdującego się w katalogu z plikiem crontab (lub względną ścieżkę do niego).</p> | |
| 509 | ||
| 510 | <script type="text/javascript"> | |
| 511 | // <![CDATA[ | |
| 512 | function generateToc() { | |
| 513 | var menu = document.createElement('ol'); | |
| 514 | document.getElementById('menu').appendChild(menu); | |
| 515 | var elems = document.querySelectorAll('h3,h4'); | |
| 516 | var now = 3; | |
| 517 | ||
| 518 | for(var i=0; i<elems.length; i++) { | |
| 519 | if(elems[i].id == '') { | |
| 520 | continue; | |
| 521 | } | |
| 522 | ||
| 523 | var level = parseInt(elems[i].tagName.slice(1)); | |
| 524 | ||
| 525 | if(level < now) { | |
| 526 | while(level < now) { | |
| 527 | menu = menu.parentNode.parentNode; | |
| 528 | now--; | |
| 529 | } | |
| 530 | } | |
| 531 | else if(level > now) { | |
| 532 | while(level > now) { | |
| 533 | if(menu.lastChild) { | |
| 534 | ol = document.createElement('ol'); | |
| 535 | menu.lastChild.appendChild(ol); | |
| 536 | menu = ol; | |
| 537 | } | |
| 538 | else | |
| 539 | { | |
| 540 | li = document.createElement('li'); | |
| 541 | ol = document.createElement('ol'); | |
| 542 | li.appendChild(ol); | |
| 543 | menu.appendChild(li); | |
| 544 | menu = ol; | |
| 545 | } | |
| 546 | ||
| 547 | now++; | |
| 548 | } | |
| 549 | } | |
| 550 | ||
| 551 | var li = document.createElement('li'); | |
| 552 | var a = document.createElement('a'); | |
| 553 | a.href = '#'+elems[i].id; | |
| 554 | a.appendChild(document.createTextNode(elems[i].textContent)); | |
| 555 | li.appendChild(a); | |
| 556 | menu.appendChild(li); | |
| 557 | } | |
| 558 | } | |
| 559 | ||
| 560 | generateToc(); | |
| 561 | // ]]> | |
| 562 | </script> | |
| 563 | ||
| 564 | </body> | |
| 565 | </html> | |
