Copyright © 2003-2004 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.
$title
Tytuł komunikatu.
$msg
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
.
$plugname
Nazwa wtyczki. Powinna być taka sama jak nazwa moduły w którym się ona znajduje.
$optname
Nazwa opcji, o którą pytamy.
$synopsis
Krótki opis opcji. Powinien pochodzić prosto z dokumentu XML opisującego tę wtyczkę.
$description
Dłuższy opis opcji. Powinien pochodzić prosto z dokumentu XML opisującego tę wtyczkę.
$default
Wartość jaka zostanie zwrócona, gdy użytkownik nie udzieli żadnej odpowiedzi.
@answers
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
.
$plugname
Nazwa wtyczki. Powinna być taka sama jak nazwa moduły w którym się ona znajduje.
$optname
Nazwa opcji, o którą pytamy.
$synopsis
Krótki opis opcji. Powinien pochodzić prosto z dokumentu XML opisującego tę wtyczkę.
$description
Dłuższy opis opcji. Powinien pochodzić prosto z dokumentu XML opisującego tę wtyczkę.
$default
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
.
$plugname
Nazwa wtyczki. Powinna być taka sama jak nazwa moduły w którym się ona znajduje.
$optname
Nazwa opcji, o którą pytamy.
$synopsis
Krótki opis opcji. Powinien pochodzić prosto z dokumentu XML opisującego tę wtyczkę.
$description
Dłuższy opis opcji. Powinien pochodzić prosto z dokumentu XML opisującego tę wtyczkę.
$default
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
plugins_options{keywords}{main.group}
Nazwa grupy z konfiguracji AddUser-NG podstawie której ma być utworzony nowy użytkownik.
plugins_options{keywords}{main.login}
Login użytkownika.
plugins_options{verbose}
Czy uruchomiono AddUser-NG parametrem
--verbose
. Innymi słowy czy
AddUser-NG ma wypisywać nadmiarowe, zazwyczaj nie
potrzebne, informacje.
plugins_options{login}
Login użytkownika. To samo co
plugins_options{keywords}{main.login}
plugins_options{documentation_dir}
Katalog, w których przechowywana jest dokumentacja wszystkich wtyczek.
plugins_options{GroupConfig}
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
plugins_options{UI}
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.
opts
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.
NAME
Nazwa wtyczki.
APIVERSION
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.