Copyright © 2003 AddUser-ng Development Team
Abstrakt
Poniższy dokument przeznaczony jest przede wszystkim dla osób, które chcą przyłączyć się do rozwoju AddUser-NG. Opisane zostało API wtyczek (pluginów) oraz interfejsu użytkownika.
Spis przykładów
Spis treści
Wszelka interakcja z użytkownikiem powinna odbywać się przy wykorzystaniu interfejsów użytkownika. Zapewniają one odpowiednią funkcjonalność wymaganą przez wtyczki, a także dają użytkownikowi komfort korzystania z AddUser-NG w sposób taki jak chce lub taki jak musi.
Wyświetl komunikat informujący o błędzie.
Tytuł komunikatu.
Treść komunikatu.
Wybór jednej opcji z kilku.
Metoda zwraca odpowiedź użytkownika (przekonwertowaną na małe litery) lub, w przypadku jej braku, wartość $default.
Nazwa wtyczki. Powinna być taka sama jak nazwa moduły w którym się ona znajduje.
Nazwa opcji, o którą pytamy.
Krótki opis opcji. Powinien pochodzić prosto z dokumentu XML opisującego tę wtyczkę.
Dłuższy opis opcji. Powinien pochodzić prosto z dokumentu XML opisującego tę wtyczkę.
Wartość jaka zostanie zwrócona, gdy użytkownik nie udzieli żadnej odpowiedzi.
Lista odpowiedzi, z spośród których może wybierać użytkownik.
Pobranie dłuższej odpowiedzi od użytkownika.
Metoda zwraca odpowiedź użytkownika lub, w przypadku jej braku, wartość $default.
Nazwa wtyczki. Powinna być taka sama jak nazwa moduły w którym się ona znajduje.
Nazwa opcji, o którą pytamy.
Krótki opis opcji. Powinien pochodzić prosto z dokumentu XML opisującego tę wtyczkę.
Dłuższy opis opcji. Powinien pochodzić prosto z dokumentu XML opisującego tę wtyczkę.
Wartość jaka zostanie zwrócona, gdy użytkownik nie udzieli żadnej odpowiedzi.
Pobranie hasła od użytkownika.
Metoda zwraca odpowiedź użytkownika lub, w przypadku jej braku, wartość $default.
Nazwa wtyczki. Powinna być taka sama jak nazwa moduły w którym się ona znajduje.
Nazwa opcji, o którą pytamy.
Krótki opis opcji. Powinien pochodzić prosto z dokumentu XML opisującego tę wtyczkę.
Dłuższy opis opcji. Powinien pochodzić prosto z dokumentu XML opisującego tę wtyczkę.
Wartość jaka zostanie zwrócona, gdy użytkownik nie udzieli żadnej odpowiedzi.
Cała siła i funkcjonalność AddUser-NG zawarta jest w mechanizmie wtyczek. Każda z nich ma dostęp do API programu oraz posiada określone metody z jakich korzysta AddUser-NG przy wykonywaniu plugina.
Każda z metod: configure, execute i rollback otrzymuje jako pierwszy argument referencję do API dostępnego dla wtyczki. Poniżej znajduje się jego struktura i opis.
API => { %plugins_options => { %keywords => { main.login, main.group }, verbose, login documentation_dir, GroupConfig (Config::IniFiles), UI, }, %opts
Nazwa grupy z konfiguracji AddUser-NG podstawie której ma być utworzony nowy użytkownik.
Login użytkownika.
Czy uruchomiono AddUser-NG parametrem --verbose. Innymi słowy czy AddUser-NG ma wypisywać nadmiarowe, zazwyczaj nie potrzebne, informacje.
Login użytkownika. To samo co plugins_options{keywords}{main.login}
Katalog, w których przechowywana jest dokumentacja wszystkich wtyczek.
Referencja do obiektu zawierającego odczytaną konfigurację grupy, na podstawie której ma być tworzony nowy użytkownik. Więcej o metodach tego obiektu dowiesz się z perldoc Config::IniFiles
Referencja do używanego interfejsu użytkownika. Przy wykorzystaniu tego obiektu odbywa się cała interacja wtyczki z użytkownikiem. W rozdziale Rozdział 1, UI -- Interfejs Użytkownika znajdziesz więcej informacji na ten temat.
Opcje konfiguracyjne wtyczki. Przy inicjalizacji powinny zostać ustawione na domyślne wartości, następnie podczas konfiguracji na wartości, które zostaną użyte podczas wykonania wtyczki.
Nazwa wtyczki.
Wersja API z jaką zgodna jest wtyczka.
Przed fazą konfiguracji wtyczek sprawdzana jest ich kompatybilność z AddUser-NG. W przypadku gdy który kolwiek plugin okaże się niezgodny działanie całego Skryptu jest przerywane. Można to zrobić bezpiecznie, gdyż do tego momentu żadna wtyczka nie powinna była wprowadzić jakichkolwiek modyfikacji do systemu.
Wersja API wtyczki jest dostępna jako atrybut APIVERSION jej obiektu. Natomiast wersja API AddUser-NG jest zapisana w zmiennej globalnej $APIVERSION.
Numery wersji podane są w postaci liczby szestnastkowej.
Podczas ładowania potrzebnych pluginów wywoływana jest metoda new każdego z nich. W jej wywołaniu wtyczka powinna zostać wstępnie skonfigurowana, np. stworzenie listy opcji konfiguracyjnych plugina i ustawienie ich na wartości domyślne.
Przykład 2.1. Szkielet metody new
sub new { my ($c, %args) = @_; my $class = ref($c) || $c; $args{opts} = { 'your_name' => '' }; bless \%args, $class; }
W momencie wywołania metody new przekazywane jej jest API.
Zanim którykolwiek plugin zostanie uruchomiony wcześniej wszystkie muszą zostać skonfigurowane. W tym celu AddUser-NG wywołuje metodę configure każdej wtyczki.
Przykład 2.2. Szkielet metody configure
sub configure { my $self = shift; # ... code follows here :) return $ERRNO{'OK'}; }
W momencie wywołania metody configure przekazywany jest niejawnie argument będący referencją do samej wtyczki, który zawiera całe jej API.
W obecnej wersji wartość zwracana przez tę metodę nie jest brana pod uwagę, ale może to ulec zmianie w kolejnych wersjach, dlatego zalecamy zwracać warotść informującą o powodzeniu (bądź też niepowodzeniu) wykonania.
Wszystkie wtyczki są uruchamiana w takiej samej kolejności jak podczas fazy konfiguracji. Dla każdej uruchamiana jest metoda execute.
Przykład 2.3. Szkielet metody execute
sub execute { my $self = shift; # ... code follows here :) return $ERRNO{'OK'}; }
W momencie wywołania metody execute przekazywany jest niejawnie argument będący referencją do samej wtyczki, który zawiera całe jej API.
W przypadku gdy wykonanie akcji przewidzianych przez daną wtyczkę powiedzie się, metoda powinna zwrćcić $ERRNO{'OK'}, w przeciwnym wypadku powinna zwrócić $ERRNO{'ERROR'}. W tym drugim przypadku AddUser-NG przerwie wykonywanie kolejnych wtyczek i zacznie cofać zmiany, więcej o tym przeczytasz w podrozdziale „Cofanie zmian (rollback)”.
W przypadku, gdy wykonanie któregoś plugina nie powiedzie się (metoda execute zwróci numer błędu inny od $ERRNO{'OK'}) AddUser-NG przerwie wykonywanie kolejnych pluginów i zacznie uruchamiać metodę rollback dla wszystkich wykonanych (włącznie z tym który zwrócił błąd). Jej zadaniem jest cofnięcie wszystkich zmian jakie wprowadziła dana wtyczka.
Przykład 2.4. Szkielet metody rollback
sub rollback { my $self = shift; # ... code follows here :) return $ERRNO{'OK'}; }
W momencie wywołania metody rollback przekazywany jest niejawnie argument będący referencją do samej wtyczki, który zawiera całe jej API.
W obecnej wersji wartość zwracana przez tę metodę nie jest brana pod uwagę, ale może to ulec zmianie w kolejnych wersjach, dlatego zalecamy zwracać warotść informującą o powodzeniu (bądź też niepowodzeniu) wykonania.