___ ___ ______ _______ __ __ __ ___ ___ | \/ | / __ \ | __ \ | | | | | |__ \ \ / / | \ / | | | | | | | \ | | | | | | ' / \ \/ / | |\/| | | | | | | | | | | | | | | / \ / | | | | | |__| | | |__/ | | |__| | | |____ | | |__| |__| \______/ |_______/ \______/ |_______| |__| Poradnik v0.94 Tworzenie i edycja
Należy w katalogu /modules/ utworzyć plik (kodowanie znaków UTF-8, bez BOM) o nazwie w postaci:
(dwie cyfry)_(nazwa).php
np.
99_nazwa.php
Plik ten powinien zawierać klasę (nazwa) implementującą module...
<?php
class nazwa implements module
{
oraz co najmniej dwie statyczne metody: register_cmd i help
static function register_cmd()
{
}
static function help($cmd = NULL)
{
}
Jeśli moduł posiada dane, które musi przechowywać (np. słownik, tabelę kursów itp.), należy zapisać je w katalogu ./data/(nazwa_modulu)/ - w taki też sposób należy odwoływać się do zasobu w skrypcie.
Jeśli moduł musi przechowywać dane dot. użytkownika, należy wykorzystać funkcje opisane w punkcie C.: Do czego służy klasa database?
W każdej chwili w zmiennej $_GET['from'] znajduje się numer (GG) lub identyfikator (IMified.com) nadawcy wiadomości, a w zmiennej $_GET['to'] - numer (GG) lub kod (IMified.com) bota.
Błąd składniowy w pliku z modułem może powodować błędy w działaniu całego bota!
Funkcja register_cmd() ma zwracać tablicę następującej postaci:
'komenda' => 'funkcja_klasy',
'komenda2' => 'funkcja_klasy'
'komenda' nie może zawierać polskich znaków ani wielkich liter.
Przykład - rejestrowanie i deklaracja komendy przyklad:
class przyklad implements module {
static function register_cmd() {
return array(
'przyklad' => 'cmd_przyklad',
);
}
// Nie uwzględniono tu wymaganej funkcji help()
static function cmd_przyklad($komenda, $argumenty) {
GGapi::putText('Wywołałeś przykładową komendę z argumentami: '.$argumenty);
}
}
Funkcja help() przyjmuje argument $cmd - nazwę komendy dla której ma zwrócić, za pośrednictwem GGapi, pomoc. Jeśli argument ten jest identyczny z NULL, należy zwrócić skróconą listę poleceń z krótkim wyjaśnieniem, zakończoną dwoma znakami nowej linii.
Przykład - funkcja help():
static function help($cmd = NULL) {
if($cmd === NULL) {
GGapi::putRichText('przyklad ', TRUE);
GGapi::putRichText('[argument]', FALSE, TRUE);
GGapi::putRichText("\n".' Przykładowa komenda'."\n\n");
}
else
{
GGapi::putRichText('przyklad ', TRUE);
GGapi::putRichText('[argument]', FALSE, TRUE);
GGapi::putRichText("\n".' Komenda zwraca przykładowy test oraz treść argumentu ');
GGapi::putRichText('[argument]', FALSE, TRUE);
}
}
GGapi to klasa stworzona specjalnie na potrzeby tego bota Gadu-Gadu, ułatwiająca komunikację z serwerem GGapi.
Funkcja putText() jest zadeklarowana następująco:
static function putText($text);
Zachowuje ona $text, który ma być wysłany do klienta Gadu-Gadu.
Jeśli wcześniej zostało ustawione formatowanie, np. za pomocą putRichText(), to zostanie ono zachowane.
Funkcja putRichText() jest zadeklarowana następująco:
static function putRichText($text, $bold=FALSE, $italic=FALSE, $underline=FALSE, $R=0, $G=0, $B=0);
Działa ona podobnie do funkcji putText(), ale można to dodatkowo ustalić formatowanie tekstu.
Drugi argument oznacza pogrubienie tekstu,
trzeci określa pochylenie,
czwarty podkreślenie,
kolejne to składowe czerwona ($R), zielona ($G) i niebieska ($B) ewentualnego koloru tekstu w palecie RGB.
Przykład - wysyłanie tekstu sformatowanego:
GGapi::putRichText('Tekst pogrubiony', TRUE);
GGapi::putRichText(' Tekst pochylony', FALSE, TRUE);
GGapi::putRichText(' Tekst zwykły');
W ostatej linii nie wystarczy zastosować GGapi::putText(), gdyż formatowanie zostałoby zachowane (tekst byłby pochylony).
Funkcja putImage() jest zadeklarowana następująco:
static function putImage($image);
Zachowuje ona obrazek zapisany w pliku $image w celu wysłania go do klienta Gadu-Gadu.
Jeśli obrazek nie istnieje, badź nie można go odczytać - funkcja zwróci FALSE.
Metoda nie działa (zwraca FALSE) przy wywołaniu bota z API IMified.com!
Funkcja getLength() jest zadeklarowana następująco:
static function getLength();
Zwraca ona sumaryczną długość tekstu zapisanego za pomocą funkcji GGapi::putText i GGapi::putRichText.
Wartość ta pozwala zapobiegać dzieleniu wiadomości na części i wysyłaniu zbyt dużej ilości treści np. z kanałów RSS.
Klasa database służy do przechowywania danych dotyczących użytkownika. Przykładem wykorzystania tej klasy jest moduł pogoda, w którym miasto użytkownika zostało zapisane, w celu podawania prognozy bez konieczności każdorazowego dopisywania do komendy nazwy miejscowości.
Nowe dane zawsze nadpisują starsze!
W przypadku konieczności zapisania danych niezwiązanych z konkretnym użytkownikiem, a na przykład z działaniem skryptu, można w polu numer podać liczbę ujemną lub ciąg znaków (nie ma wymogu, by w polu $numer znalazła się liczba).
Funkcja add() słuzy do zapisywania jednej pary nazwa - wartość danych i jest zdefiniowana następująco:
static function add($numer, $modul, $name, $value);
$numer to numer użytkownika, $modul oznacza nazwę modułu, który dane przechowuje, $name to nazwa zmiennej, a $value to jej wartość.
Przykład:
database::add($_GET['from'], 'przyklad', 'zmienna', 'wartosc');
Funkcja addArray() słuzy do zapisywania całej tablicy danych i jest zdefiniowana następująco:
static function addArray($numer, $modul, $name_value);
$numer to numer użytkownika, $modul oznacza nazwę modułu, który dane przechowuje, a $name_value to tablica z polami w formacie: 'nazwa' => 'wartosc'
Przykład:
$dane = array(
'czas' => time(),
'data' => date('d.m.Y'),
'tablica' => array('a', 'b', 'c'),
);
database::addArray($_GET['from'], 'przyklad', $dane);
Funkcja get() służy do pobrania wartości skojarzonej z jedną nazwą zmiennej i jest zdefiniowana następująco:
static function get($numer, $modul, $name);
$numer to numer użytkownika, $modul oznacza nazwę modułu, który dane przechowuje, a $name to nazwa żądanej zmiennej.
Jeśli podana zmienna nie istnieje, funkcja zwróci FALSE
Przykład:
database::add($_GET['from'], 'przyklad', 'zmienna', 'wartosc');
$zmienna = database::get($_GET['from'], 'przyklad', 'zmienna');
assert($zmienna == 'wartosc');
Funkcja getArray() słuzy do pobierania całej tablicy danych i jest zdefiniowana następująco:
static function getArray($numer, $modul);
$numer to numer użytkownika, a $modul oznacza nazwę modułu, który dane przechowuje.
Jeśli żadne zmienne nie zostały zapisane, funkcja zwróci pustą tablicę
Przykład:
database::delAll();
$dane = array(
'czas' => time(),
'data' => date('d.m.Y'),
'tablica' => array('a', 'b', 'c'),
);
database::addArray($_GET['from'], 'przyklad', $dane);
$zmienna = database::getArray($_GET['from'], 'przyklad');
assert($zmienna == $dane);
Wykonanie funkcji powoduje dodanie (patrz: array_merge()) nowych danych do wcześniej zapisanych
Funkcja del() słuzy do usuwania pojedynczych danych i jest zdefiniowana następująco:
static function del($numer, $modul, $name);
$numer to numer użytkownika, $modul oznacza nazwę modułu, który dane przechowuje, a $name to nazwa usuwanej zmiennej.
Funkcja delAll() słuzy do usuwania wszystkich danych przechowywanych przez moduł na temat danego numeru.
static function delAll($numer, $modul);
$numer to numer użytkownika, a $modul oznacza nazwę modułu, który dane przeznaczone do usunięcia przechowuje.
Jeśli istnieje potrzeba okresowego aktualizowania danych (np. kursów walut) można użyć do tego przygotowanego specjalnie dla tego bota narzędzia.
W folderze /data/(nazwa modułu)/ należy utworzyć plik crontab, zgodny ze składnią crontaba.
Przykład pliku crontab:
# To jest komentarz - znak # musi być pierwszym znakiem w linijce!
# Uruchamiaj się codziennie, co dwie godziny, między północą a dwudziestą.
0 0-20/2 * * * co_dwie_godziny.php
# Uruchamiaj się o 4:00 w każdą niedzielę
0 4 * * 0 niedziela.php
# Uruchamiaj się w każdy poniedziałek i środę o 10:00
0 10 * * 1,3 pon_sr_10.php
Pierwsze pole (minuty) jest pomijane, tj. nie można uruchamiać programu częsciej niż raz na godzinę!
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).
Poniższe klasy zawierają funkcje często używane w modułach.
Metoda parse_date klasy calendar jest zdefiniowana następująco:
static function parse_date($date);
Przetwarza ona tekst $date (np. 'wczoraj', 'jutro', ale także '1 stycznia 2000') na uniksowy znacznik czasu, który zwraca.
Przykład:
$data = calendar::parse_date('29 stycznia 2009');
$wzor = mktime(0, 0, 0, 1, 29, 2009);
assert($data == $wzor);
Metoda utfToAscii klasy funcs jest zdefiniowana następująco:
static function utfToAscii($utf);
Polskie znaki w zmiennej $utf zamienia w litery alfabetu angielskiego (ó => o, ź => z itd.), wykonuje na tekście strtolower() oraz trim(), po czym zwraca tak zmodyfikowaną treść.
Metoda end klasy funcs jest zdefiniowana następująco:
static function end();
Kończy wykonywanie skryptu, jednak, w przeciwieństwie do die(), wysyła dodatkowo wszystkie zapisane za pomocą GGapi części wiadomości do użytkownika.
Przykład:
funcs::end();