Artykuł

wrz 25 2010
0

Wtyczka do obsługi formularzy w jQuery i HTML5

Podczas developerki nowej odsłony Alt Control Delete, stworzyłem również wiele kodu, który myślę, że z powodzeniem mógłby zostać wykorzystany w innych projektach. Jednym z takich przykładów, jest wtyczka jQuery do obsługi formularzy, którą nazwałem Form and Ajax - prawda, że wymyślna nazwa:)?

Idea działania wtyczki Form and Ajax

Idea działania wtyczki jest prosta - w pełni obsłużyć formularz. Co należy jednak rozumieć przez termin pełna obsługa formularza? Już spieszę z wyjaśnieniem. Jest to ogół czynności związanych z obsługą formularza, czyli przede wszystkim jego walidacja (to czy wymagane pola zostały uzupełnione) oraz możliwość jego wysłania, zarówno przez tradycyjną funkcję Submit jak też i przez Ajaxa. Przy zastosowaniu tego drugiego wariantu, konieczna jest również obsługa odpowiedzi zwróconej przez Ajax. Wszystkie te zadania, realizuje właśnie wtyczka, której kod źródłowy znajdziecie poniżej.

Kod źródłowy wtyczki

Kod źródłowy wtyczki (skromne 60 linii), znajduje się poniżej:

jQuery.fn.extend({
	FormAndAjax : function(oOptions){
		var oDefaults = {
			sUrl: "index.php",
			sFormSelector: "form",
			sMessageElementSelector: "#msg",
			sSuccessClass: "success",
			sErrorClass: "error",
			sFieldErrorClass: "field-error",
			bAjax: true
		}
		var oOptions = jQuery.extend(oDefaults, oOptions);
		return this.click(function() {
			var bEachReturn = true;
			var oForm = $(oOptions.sFormSelector);
			var oMessageElement = $(oOptions.sMessageElementSelector);
			oMessageElement.html("");
			oMessageElement.removeClass(oOptions.sSuccessClass);
			oMessageElement.addClass(oOptions.sErrorClass);	
			oForm.find("[data-required='true']").each(function(nIndex){
				if("" == $(this).val()){
					bEachReturn = false;
					$(this).addClass(oOptions.sFieldErrorClass);
				}
			});
			if(!bEachReturn){
				oMessageElement.html("Proszę wypełnić wszystkie wymagane pola.");
				return false;
			}
			if(oOptions.bAjax){
				$(this).attr("disabled", "disabled");
				var sData = oForm.serialize();
				$.ajax({
					type: "POST",
					url: oOptions.sUrl,
					data: sData, 
					async: false,
					dataType: "json",
					success: function(oJsonObject) {
						switch(oJsonObject.errorcode){
							case 0:
								oMessageElement.removeClass(oOptions.sErrorClass);
								oMessageElement.addClass(oOptions.sSuccessClass);
								break;
						}
						oMessageElement.html(oJsonObject.errordesc);
					}, 
					error: function(oXMLHttpRequest, sTextStatus) {
						oMessageElement.html("Wystąpił błąd przy połączeniu z serwerem: " + 
							sTextStatus);
					}
				});	
				$(this).removeAttr("disabled");
			} else {
				oForm.submit();
			}
		});			
	}}
);

Jak widać, na załączonym listingu, wtyczka ma raczej dość charakterystyczną dla jQuery budowę. Przyjrzyjmy się jednak pokrótce, najciekawszym elementom.

W liniach 3-11, zostały zdefiniowane wartości domyślne najważniejszych parametrów wtyczki. Omówię teraz każdy z nich, ponieważ ich stosowne użycie, warunkuje poprawność działania wtyczki.

  • sUrl - nazwa pliku, do którego ma zostać przesłane żądanie Ajax
  • sFormSelector - selektor, przechowujący identyfikator formularza, z którego dane mają zostać przetworzone
  • sMessageElementSelector - selektor elementu, który przechowuje informacje zwróconą przez zapytanie Ajax
  • sSuccessClass - klasa CSS, która zostania dodana do selektora informacji w przypadku kiedy zapytanie Ajax się powiedzie
  • sErrorClass - j/w, z tym, że jest to klasa używana w przypadku błędu
  • sFieldErrorClass - klasa CSS używana do oznaczenia pól formularza, które nie zostały wypełnione
  • bAjax - flaga, która decyduje o tym czy formularz ma zostać wysłany za pomocą Ajaxu, czy też klasycznie

Jak widać, większość z opcji zaszytych w kodzie wykorzystywana jest tylko w przypadku formularzy korzystających z Ajaxa. Przejdźmy teraz, do dalszego omówienia kodu. Kod w linii 12, kojarzy wartości domyślne parametrów, z wartościami użytkownika. Innymi słowy, jeśli użytkownik nie poda dla danego parametru jakiejś nowej wartości, to zostanie wykorzystana wartość domyślna.

Kod od linii 13, aż do końca wywoływany jest po zdarzeniu kliknięcia przycisku, do którego podpięta została ta wtyczka. Na wstępie tego kodu, widać operacjetypowo porządkowe, czyli dodawanie/usuwanie klas, czyszczenie elementów itp.

Ciekawsze rzeczy, możemy znaleźć w liniach od 20 do 29. Znajduje się tu mechanizm weryfikacji wypełnienia pól. Założenie tego mechanizmu jest proste. Każde pole, którego ma zostać wypełnione, musi posiadać atrybut data-required ustawiony na wartość true. Atrybut ten, możemy wykorzystywać dzięki HTML5, który pozwala na tworzenie własnych atrybutów rozpoczynających się od ciągu data-. Wróćmy jednak do kodu. Każde pole, znajdujące się w obrębie formularza, zostaje sprawdzone pod kątem tego atrybutu. Jeśli okaże się, że istnieją pola, które nie zostały wypełnione, a są wymagane, to skrypt poinformuje o tym użytkownika i zaznaczy te pola wykorzystując klasę zdefiniowaną w parametrze sFieldErrorClass. Przetwarzanie zostanie przerwane.

W liniach 30-56 znaleźć możemy ostatni etap pracy wtyczki, czyli funkcje wysłania formularza. Tak jak widać w kodzie, może być ona zrealizowana za pomocą Ajaxa, lub klasycznie, wszystko to jest uzależnione od parametru bAjax, który został omówiony wcześniej.

Ponieważ o Ajaxie w jQuery pisałem nie dawno, to zwrócę teraz uwagę tylko na jedną rzecz. Użytkownik, który implementuje opisywaną tutaj wtyczkę, powinien się zatroszczyć o poprawny format odpowiedzi zapisany w Json. W przypadku tej wtyczki ma on następującą postać:

{"errorcode": kod_bledu, "errordesc": "opis_bledu"}

Wartość kod_bledu należy oczywiście zastąpić odpowiednią liczbą sygnalizującą sukces (0) lub porażkę. Opis błędu, jest oczywiście normalnym stringiem. (Jeśli chcesz się dowiedzieć więcej, jak wysłać Jsona do skryptu JavaScript z poziomu PHP, przeczytaj koniecznie Widget Twitter w PHP i jQuery na stronie).

Sposób użycia wtyczki

Tak jak wspomniałem, wtyczka działa w dwóch trybach: z Ajaxem i bez. Do ustawienia trybu, służy przełącznik bAjax, który również został opisany wyżej. Przykładowy kod strony (napisanej koniecznie w HTML5!) wykorzystującej niniejszą wtyczkę, może wyglądać tak (wersja Ajax):

<!DOCTYPE html>
<html lang="pl">
    <head>
        <meta charset="utf-8" />
        <link type="text/css" rel="stylesheet" href="css/formandajax.css" />
        <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js" type="text/javascript"></script>
        <script type="text/javascript" src="js/jquery.formandajax-min.js"></script>
        <title>Przykład</title>
        <script type="text/javascript">
        $(document).ready(function () {
            $("#btnsubmit").FormAndAjax({
                sFormSelector: "#myform",
                sMessageElementSelector: "#mymsg"
            });
        });        
        </script>
    </head>
    <body>
        <form action="#" id="myform">
            <label for="name">Imię</label>
            <input type="text" name="name" id="name" data-required="true" /><br />
            <label for="surname">Nazwisko</label>
            <input type="text" name="surname" id="surname" data-required="true" /><br />            
            <label for="age">Wiek</label>
            <input type="text" name="age" id="age" /><br />
            <input type="submit" name="submit" id="btnsubmit" value="Wyślij" />
        </form>
        <p id="mymsg"></p>
    </body>
</html>

Jak widać, wywołanie wtyczki nie powinno nastręczać problemów. Wykorzystaliśmy tutaj standardową konstrukcję, która aktywuje wtyczkę formularza po załadowaniu strony. Wszystko to, skojarzone zostaje z przyciskiem submit za pomocą jego unikalnego identyfikatora. Dla przykładu, zmieniłem również 2 wartości domyślne wtyczki. W tym przypadku, jest to konkretnie identyfikator formularza oraz identyfikator akapitu, który przechowywać będzie informacje o błędzie.

Kolejnym aspektem, na który warto zwrócić uwagę, to atrybut data-required wykorzystywany przez wtyczkę. Jak widać na załączonym listingu, dwa z trzech pól posiadają ten atrybut i tym samym są wymagane.

Jeśli chcielibyśmy wykorzystać ten kod do wtyczki w wersji bez Ajaxa, to należałoby dokonać kilku modyfikacji. Przede wszystkim, należało by określić akcję formularza w standardowy sposób oraz przełączyć flagę bAjax. Kody dla obu wariantów, można znaleźć w dziale Download.

Podsumowanie

Wtyczka przedstawiona w niniejszym wpisie na pewno nie jest doskonała i wymaga trochę pracy, jednak w przypadku mojej strony, bez problemu obsłużyła wszystkie dostępne formularze. Kompletną wtyczkę ze wszystkimi niezbędnymi plikami, możecie znaleźć w dziale Download. Jeśli zamierzacie jej użyć, prosiłbym o pozostawienie informacji na temat autora oraz linku do tej strony.

Data ostatniej modyfikacji: 25.07.2013, 14:31.

Podoba Ci się ten wpis? Powiedz o tym innym!

Send to Kindle

Komentarze

blog comments powered by Disqus