ActionsManager

ActionsManager to biblioteka js, która umożliwia zarządzanie akcjami ajaxowymi na naszej stronie. Prosty przykład:
Mamy tabelę i chcemy zrobić podgląd jej jakiegoś wiersza. Podgląd miałby być w divie. Zamiast pisać długie kody do pobrania danych poprzez ajax, wstawienie tego do diva, wystarczy wywołać prostą komendę i już. Klasa dostarcza również kilka pluginów, które odpowiadają za przesuwanie okienka (diva), zmiane jego rozmiarów, pozycjonowanie. Ponadto sama w sobie zawiera dużą możliwość konfiguracji. Można ją dowolnie rozszerzać by dostosować do własnych specyficznych potrzeb.

Atutem tej klasy może być również fakt, iż dzięki niej można zachować jednolitą obsługę wszystkich naszych akcji. Dodatkowo klasa może działać z dowolnymi bibliotekami ajaxowymi, wystarczy tylko załadować odpowiedni plugin.

Spis treści

Istota działania

Jak to działa? Prosto. Odpalamy akcję, pojawia nam się okienko akcji i leci poprzez ajax żądanie do serwera by obsłużył akcję. Serwer robi co ma robić i zwraca nam wynik akcji. W zależności od tego jakiego typu danych oczekujemy dostajemy albo xml, albo html albo coś innego. Jeśli to jest xml, to możemy dostać komunikaty o ewentualnych błędach lub też zwykle komunikaty informacyjne. Wszystko to co zwróci nam serwer zobaczymy w okienku akcji. Oczywiście okiekno akcji można w duży sposób konfigurować, ale o tym później.

Instalacja

Instalacja jest banalnie prosta. Należy poprostu dołączyć odpowiednie pliki js do naszej strony:

<script src="sciezkadoskryptow/ActionsManager.js" type="text/javascript"></script>
<script src="sciezkadoskryptow/Mixed.js" type="text/javascript"></script>

Plik Mixed.js zawiera pare metod, które często używam w różnych bibliotekach, dlatego go wyodrębniłem. Ponieważ klasa działa z dowolnymi bibliotekami do obsługi ajaxa, należy jeszcze załadować odpowiedni plugin. Jeśli korzystamy z advajaxa, to piszemy np. tak:

<script src="sciezkadoskryptow/ActionsManager_advAjax.js" type="text/javascript"></script>

Narazie napisane mam pluginy do advajaxa i prototype.
Jeśli chcemy też mieć ładny wygląd, należy też dołączyć plik css

<link rel="stylesheet" href="sciezkadocss/ActionsManager.css" type="text/css" />

Rozszerzenia (plugins)

Klasa może być łatwo wzbogacana o dodatkowe możliwości, poprzez zastosowanie pluginów. Na chwilę obecną napisałem plugin do poruszania okienkiem akcji oraz zmianę jego rozmiarów, plugin do centrowania okienka względem okna przeglądarki lub innego diva, plugin do "szybkiej edycji". W prosty sposób można pisać własne rozszerzenia. Należy pamiętać o konwencji nazewnictwa jaką przyjąłem: ActionsManager_pluginname.js, gdzie pluginname to nazwa pluginu. Aby moć skorzystać z danego rozszerzenie, należy go dołączyć do strony. Można do zrobic na dwa sposoby:

  • dołączenie skryptu pluginu (należy to zrobić po dołączeniu pliku klasy)
    <script src="sciezkadoskryptow/ActionsManager_pluginname.js" type="text/javascript"></script>
  • skorzystać z metody do tego stworzonej
    <script type="text/javascript">
    ActionsManager.loadPlugins('plugin1,plugin2,plugin3,...');
    </script>
    Jak widać z powyższego kodu, można dołączyć kilka pluginów, ale można też jeden. Domyślnie pluginy szukane są w katalogu scripts/plugins/, ale można to zmienić w zmiennej ActionsManager.pluginsPath.

Użycie

Wywołanie akcji polega na odpaleniu następującego kodu:

ActionsManager.setup(params);
, gdzie params to obiekt o następujących parametrach:
  • guid - identyfikator okienka (akcji)
    Jeśli dla kilku akcji nadamy ten sam identyfikator, otwierać się będą w tym samy oknie. Nadanie im unikalnego identyfikatora spowoduje tworzenie oddzielnego okienka dla każdej akcji.
  • link - adres pod jaki ma lecieć żądanie ajax
  • closeLastOpened - zamknięcie ostatnio otwartego okienka (domyślnie false)
  • closeAfterSuccess - zamyka okienko gdy akcja zakończy się sukcesem (domyślnie false)
    Parametr obsługiwany tylko dla akcji, których wynikiem jest xml
  • className - nazwa klasy css dla okienka (domyślnie actionsManager)
  • title - tytuł nagłówka okienka (domyślnie pusty ciąg)
  • titleRunning - tytuł nagłówka podczas trwania akcji (domyślnie null, czyli nie nadpisuje tytułu nadanego w title)
  • refresh - jeśli otwieramy okienko, które było już otwarte, to czy ponownie uruchomić akcję (domyślnie true)
  • allowRunRunning - czy pozwalać na uruchamianie akcji w danym okienku, jeśli akurat w tym okienku jakaś akcja już trwa (domyślnie false)
    Prosty przykład: nadajemy dla kilku akcji taki sam guid, czyli że mają otwierać się w tym samym okienku. No i teraz jeśli jakaś akcja trwa to albo możemy pozwolić uruchomić następną albo nie
  • messagesAddingType - w jakis sposób dodwać nowe wiadomości: first - na początku, last - na końcu (domyślnie last)
  • params - parametry przekazane razem z żądaniem do strony określonej w parametrze link (domyślnie null)
    Parametry należy przekazywać w postaci obiektu, np: {'param1' : 'wartość1', 'param2' : 'wartość2'}
  • method - metoda wysłania ządania (domyślnie post)
  • clear - czy wyczyścić zawartość okienka przed uruchomieniem akcji (domyślnie true)
  • type - typ odbieranych danych (domyślnie xml) więcej...
  • dowolny nasz parametr, który możemy przekazać do akcji i później go wykorzystać

Metoda setup() zwraca nam obiekt akcji.

Typ odbieranych danych

Akcja może obierać dane w różnej postaci, np. html, xml lub jakikolwiek inny jaki sobie ustalimy. Typ odbieranych danych określamy w parametrze wywołania type. Na chwilę obecną można odbierać dane w postaci html oraz xml. Nic nie stoi na przeszkodzie byśmy dodali nasz własny typ. Jedyne co należy zrobić to ustawić przy wywołaniu nasztyp oraz dopisać funkcję AjaxAction.prototype.writeNASZTYP = function(obj){...}, która przechwyci nasze dane i coś z nimi zrobi.

Dane typu xml powinny być następującej postaci:

<actionsmanager result="0">
	<error><![CDATA[błąd 1]]></error>
	<error><![CDATA[błąd 2]]></error>
	<error><![CDATA[.....]]></error>
	<message><![CDATA[komunikat 1]]></message>
	<message><![CDATA[komunikat 2]]></message>
	<message><![CDATA[...]]></message>
	<content><![CDATA[jakas tresc]]></content>	
</actionsmanager>

Atrybut result określa wynik wykonania akcja, przy czym 0 oznacza akcję zakończoną sukcesem, a każda inna wartość oznacza błąd akcji a wartość ta może być kodem błędu lub komunikatem jak kto woli. Znaczniki error i message mogą pojawić się wiele razy lub wogóle i przekazują błędy akcji lub komunikaty. Znacznik content powinien wystąpić conajwyżej raz i może być w nim przekazana dowolna treść jaką chcecie pokazać. Należy oczywiście pamiętać, żeby oprócz xml'a przesłać też nagłówek, który informuje przeglądarke o tym, że to właśnie xml:

<?php
header("Content-type: text/xml; charset=utf-8");
?>

Dane typu html to poprostu zwrócony kod html, który zostanie wyświetlony w okienku akcji.

Ważniejsze metody i właściwości

Biblioteka ta składa się z dwóch części:

  • ActionsManager
    Klasa do zarządzania akcjami. Główne metody i właściwości:
    • ActionsManager.setup(params)
      Inicjalizuję akcję. Metoda opisana była wcześniej
    • ActionsManager.loadPlugins(plugins)
      Wgrywa pluginy. Przykład użycia podany był wcześniej
    • ActionsManager.beforeSetup(params)
      Wywoływana jest przed inicjalizacją akcji. Przyjmuje parametry akcji a zwraca false, jeśli akcja ma nie zostać zainicjalizowana.
    • ActionsManager.destroy(object)
      Niszczy podany obiekt akcji
    • ActionsManager.hide(object)
      Chowa podany obiekt (okienko)
    • ActionsManager.show(object)
      Pokazuje podany obiekt (okienko)
    • ActionsManager.getObject(guid)
      Zwraca obiekt akcji o zadanym identyfikatorze
    • ActionsManager.pluginsPath
      Ścieżka do pluginów
    • ActionsManager.txtClose
      Tekst zamknięcia okna
    • ActionsManager.txtRunning
      Tekst trwania akcji
    • ActionsManager.lastOpened
      Obiekt ostatnio otwartej akcji
  • AjaxAction
    Obiekt akcji, który tworzony jest przez ActionsManager podczas wywołania metody setup(). Główne metody i właściwości:
    • afterSetup()
      Metoda uruchamiana po inicjalizacji akcji
    • beforeRun()
      Metoda uruchamiana przed uruchomieniem akcji. Jeśli zwróci false, akcja nie zostanie wykonana.
    • afterRun(ajaxObj,params, resultOk)
      Metoda uruchamiana po uruchomieniem akcji. Jako parametry wywołania przyjmuje obiekt ajaxa, parametry wywołania akcji, oraz informację, czy akcja zakończyła się sukcesem w sensie ajaxowym. Parametry wywołania akcji są tutaj podawane pomimo, że obiekt akcji zawiera te parametry. Zrobione jest to z tego względu, gdyż czasami te parametry mogą się różnić, np. podczas wykonywania kilku akcji w tym samym oknie.
    • setTitle(title)
      Ustawia tytuł okna akcji. Jeśli podamy null, tytuł nie zostanie ustawiony.
    • setZIndex()
      Ustawia okienko ponad wszystkimi innymi
    • getResult(ajaxObj)
      Pobiera rezultat akcji dla danych xml
    • addMessage(message, type)
      Wpisuje do okienka akcji komunikat (type="message") lub błąd (type="error")
    • clear()
      Czyści okienko z komunikatów i treści
    • params
      Parametry akcji przekazane podczas inicjalizacji
    • element
      Obiekt DOM głównego okienka
    • objects
      Zawiera obiekty DOM okienka:
      • header
        Nagłówek okienka
      • wait
        W tym divie pojawiać się będzie ikonka czekania
      • close
        W tym divie pojawiać się będzie ikonka zamknięcia
      • container
        Div ten zawiera div z wiadomościami, błędami i treścią
      • errors
        W tym divie pojawiać się będą błędy
      • messages
        W tym divie pojawiać się będą wiadomości
      • content
        W tym divie pojawiać się będzie treść

Własne przeróbki

Zapewne zdarzy się iż będziemy chcieli dodawać własną funkcjonalność. Jest to w zasadzie banalne do zrobienia. Przykładowo jeśli chcemy coś zrobić przed inicjalizacją akcji, nadpiszmy metodę beforeSetup:

//zapamietanie starej metody
ActionsManager.oldbeforeSetup = ActionsManager.beforeSetup;
//napisanie naszej nowej 
ActionsManager.beforeSetup = function(params){
	if (!ActionsManager.oldbeforeSetup(params)) // uruchomienie starej by zachować jej funkcjonalność
		return false;
//tutaj jakies nasze rzeczy
//....
return true;
}

Na podobnej zasadzie należy wzbogacać inne metody.

Komentarze

 

Dodaj komentarz

 

Dostępne bbcode: b, u, i, url, code, php, css, html, sql, js

Ostatnio komentowane

  1. Pager 2.5.1 oraz EPa... Na szybko2
  2. Pager 2.5.1 oraz EPa... Sławek
  3. Mysql - FAQ Piotr
  4. Liczba dni roboczych Na szybko2
  5. Liczba dni roboczych Naszybko
  6. Klasa widoku nospor
  7. Klasa widoku freebox

Ostatnio na forum

  1. programista php-webm... pracamatysart
  2. Programista PHP/ Mag... Create Magento 2 Marketplace
  3. Baza Danych gosc
  4. Baza Danych YankeS
  5. Baza Danych gosc
  6. Baza Danych YankeS
  7. Problem z bazą danyc... Baza Danych

Skrypty użytkowników

  1. Klasa obsługi szablo... Lirdoner
  2. Sekcje user76
  3. Klasa walidująca for... user76
  4. Licznik Gości online korey
  5. Form Builder Comandeer
  6. Dynamiczny licznik z... korey
  7. Captcha Comandeer