Ostatnio jeden z czytelników tego bloga zadał mi pytanie związane o okna modalne Bootstrap. To skłoniło mnie do poszperania trochę w dokumentacji wtyczek jQuery do Bootstrap’a. Po bliższym zapoznaniu się z tą tematyką uznałem, że może z tego powstać całkiem ciekawy i użyteczny wpis – i oto efekt :) Zresztą nie ma co przedłużać, przejdźmy zatem do rzeczy!

Funkcje JavaScript w Bootstrap

Na początek krótkie wprowadzenie. W Bootstrap 3, dostępnych jest kilkanaście wtyczek jQuery rozszerzających Bootstrap o różne opcje interakcji użytkownika z elementami interfejsu użytkownika. Standardowo, wszystkie wtyczki zaimplementowane są w pliku bootstrap.js (lub w jego wersji „zminifikowanej” czyli bootstrap.min.js), który standardowo znajduje się strukturze katalogów Bootsrap’a. Można też zamiast tego pobrać sobie wydzielone pliki JavaScript zawierające kod poszczególnych plugin’ów – w dzisiejszym wpisie skupię się na wtyczce, która znajduje się w pliku modal.js.

Wszystkie wtyczki posiadają API znaczników HTML tzn. do podstawowego ich użycianie ma potrzeby pisania ani jednej linii kodu JavaScript – zamiast tego wystarczy nadać elementom HTML odpowiednie atrybuty dostępne we wspomnianym API danej wtyczki. Oczywiście jeśli zajdzie taka potrzeba, można skorzystać z API JavaScript i odpowiednio skonfigurować działanie danej wtyczki bezpośrednio ze skryptu JavaScript.

Pełna dokumentacja wtyczek jQuery dla Bootstrap’a możecie znaleźć na stronie projektu.

Wtyczka do obsługi okien modalnych – modal.js

Bootstrap Modal (czyli po naszemu okna modalne Bootstrap) jest JavaScript’owym okienkiem wyskakującym (pop-up), który jest w pełni konfigurowalny i „responsywny”. Jest to świetny sposób by łatwo, nawet bez pisania kodu JS, stworzyć spełniające wszelkie standardy okienka pop-up na tworzonych przez nas stronach internetowych. Domyślnie, takie okienko wygląda mniej więcej w ten sposób:

Bootstrap - okna modalne

Powyższy obrazek pokazuje, że takie okno modalne posiada trzy sekcje: tytuł, treść i przyciski. Aby w ogóle móc pokazywać okienko takie jak powyżej, należy do kodu HTML naszej strony należy dodać następujący kod:

<div class="modal fade" id="myModal" tabindex="-1" role="dialog" aria-labelledby="myModalLabel" aria-hidden="true">
  <div class="modal-dialog">
    <div class="modal-content">
      <div class="modal-header">
        <button type="button" class="close" data-dismiss="modal" aria-hidden="true">&amp;times;</button>
        <h4 class="modal-title">Modal title</h4>
      </div>
      <div class="modal-body">
        One fine body…
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-default" data-dismiss="modal">Close</button>
        <button type="button" class="btn btn-primary">Save changes</button>
      </div>
    </div> <!-- /.modal-content -->
  </div><!-- /.modal-dialog -->
</div><!-- /.modal -->

Objaśnienie kodu

Należy tutaj zwrócić uwagę na kilka elementów. Po pierwsze klasa CSS nadana elementowi najbardziej zewnętrznemu elementowi div to „modal” powoduje odpowiednie sformatowanie okienka wyskakującego i nadaje mu od razu styl display: none czyli na początku jest ono niewidoczne. Druga sprawa to identyfikator „myModal” - posłuży nam on do przypisania tego okna do odpowiedniego wyzwalacza (o tym za chwilę).

Jednym z wewnętrznych elementów div ma nadaną klasę „modal-content”. To w jego wnętrzu definiujemy zawartość okna modalnego. Jak już wspomniałem, dzieli się ono na trzy sekcje: nagłówek znajduje się wewnątrz elementu z klasą „modal-header”, treść okna wewnątrz elementu z klasą „modal-body”, natomiast przyciski czyli stopka w elemencie posiadającym klasę „modal-footer”. Stopka ma domyślnie nadany styl align: right a więc przyciski znajdą się po prawej stronie. Zwróćcie także uwagę na przycisk „Close” – posiada on atrybut data-dismis powodujący, że jego kliknięcie po prostu zamyka okno i odrzuca ewentualne zmiany. Ten sam atrybut posiada przycisk znajdujący się w nagłówku – jest to guzik „X” w prawym górnym rogu ekranu (za jego odpowiednie sformatowanie i pozycjonowanie odpowiada klasa „close”). Co do guzika „Save changes” to oczywiście jego odpowiednie obsłużenie leży już w naszej gestii w zależności od tego co dane okno modalne ma robić.

Myślę, że teraz większość elementów okienka modalnego jest już jasna. Wspomniałem wcześniej o wyzwalaczu okna modalnego. Może to być zwykły link lub przycisk z nadanymi odpowiedniemi atrybutami, coś podobnego do tego poniżej:

<button class="btn btn-primary btn-lg" data-toggle="modal" data-target="#myModal">
  Open modal!
</button>

To co tutaj ważne to atrybut data-toggle informujący Bootstrap, że dany guzik otwiera okno modalne oraz atrybut data-target wskazujący, który konkretnie element ma zostać otwarty jako owe okno modalne.

To tyle z podstaw, pora teraz na trochę szczegółów dotyczących różnych opcji konfiguracyjnych naszego okna modalnego!

Okna modalne Bootstrap – zmiana rozmiaru

Tak jak wszystko w Bootstrap, tak i okna modalne Bootstrap są w pełni „responsywne” i ładnie dostosowują się do zmieniającego się rozmiaru okna. Dodatkowo mamy możliwość sterować ich rozmiarem za pomocą klas CSS dostarczanych przez Bootstrap. Domyślnie mamy dwie możliwość: okno małe i duże. Możemy tym sterować za pomocą klas modal-sm (dla małego okna) i modal-lg (dla okna dużego), które nadajemy elementowi z klasą modal-dialog z przykładu powyżej.

Oczywiście to tylko ustawienia domyślne, które możemy dowolnie modyfikować, co opisałem już w osobnym wpisie.

Kontrolowanie okien modalnych z poziomu jQuery

Jako że okna modalne Bootstrap są wtyczką jQuery, możliwe jest również aktywowanie, czyli de facto utworzenie wyzwalacza okna, z poziomu JavaScript właśnie za pomocą jQuery. Co do zasady, taka aktywacja nie różni się niczym od innych wtyczek jQuery – mając zdefiniowane w poprzednim przykładzie okno modalne, jego podpięcie do mechanizmu okien modalnych Bootstrapa wygląda mniej więcej tak:

$('#myModal').modal(options);

A więc, wystarczy za pomocą selektora jQuery pobrać referencję do okna modalnego, a następnie wywołać na nim metodę „modal” i przekazać do niej obiekt zawierający opcje.

Konfiguracja

Obiekt ten może posiadać poniższe właściwości:

var options = {
    backdrop: true,
    keyboard: false,
    show: false,
    remote: false
};

Tak wygląda obiekt opcji, jeśli chcemy zdefiniować wszystkie możliwe parametry. Oczywiście możemy część z nich pominąć – wówczas wykorzystane zostaną parametry domyślne. A poniżej opis poszczególnych parametrów:

  • backdrop – ma trzy możliwe ustawienia: true (domyślnie), false lub „static” – dwa pierwsze określają czy okno modalne będzie miało „pod spodem” wyszarzone tło czy tez nie; trzeci parametr włącza zamykanie okna modalnego poprzez kliknięcie w tło (co oznacza, że jest ono w tym momencie włączone)
  • keyboard – możliwe ustawienia to true (domyślnie) lub false; jeśli ustawiono wartość true, okno modalne będzie zamykane również za pomocą przycisku „Esc” na klawiaturze
  • show – również przyjmuje wartość boolowską czyli true (domyślnie) lub false; jeśli ta opcja jest włączona, okno pokaże się podczas inicjalizacji
  • remote – najciekawsza funkcja pozwalająca załadować do wnętrza elementu z klasą modal-content zawartość z innego pliku; można za jej pomocą przekazać ścieżkę do pliku lub ustawić jej wartość false jeśli nic nie ma być ładowane (jest to ustawienie domyślne)

Wszystkie powyższe opcje mogą być również ustawione w kodzie HTML za pomocą odpowiednich atrybutów wg schematu data-* czyli dla ustawienia remote, atrybut będzie miał postać data-remote.

Ustawienie remote

Zatrzymajmy się jeszcze na chwilę przy opcji remote. Oprócz dwóch sposobów opisanych powyżej, jest jeszcze trzeci sposób na załadowanie zewnętrznej zawartości do obszaru treści okna modalnego:

<a href="modal-template.html" class="btn btn-lg btn-default" data-toggle="modal" data-target="#largeModal">Open modal</a>

Jak widać, zamiast wykorzystać atrybut data-remote, wykorzystany został standardowy atrybut href, który zadziała w tym przypadku w takim sam sposób jak pozostałe dwie metody.

Metoda „modal” może też być wykorzystywana do manualnego sterowania wyświetlaniem okna modalnego. Robi się to w taki sposób:

$('#myModal').modal('toggle');
$('#myModal').modal('show');
$('#myModal').modal('hide');

W pierwszej linii mamy przełączenie okna modalnego czyli jeśli jest ono aktualnie otwarte to zostanie zamknięte i na odwrót. Druga linia po prostu próbuje pokazać okno nie ważne czy jest ono aktualnie widoczne czy też nie. Trzecia opcja robi coś odwrotnego do poprzedniej czyli stara się schować okno (jeśli jest widoczne to się schowa a jeśli nie to nic się nie wydarzy).

Zdarzenia Bootstrap okien modalnych

Bootstrap podczas pokazywania, chowania (itp.) okien modalnych wywołuje kilka zdarzeń, które możemy obsłużyć za pomocą metody „on” dostępnej w jQuery:

$('#myModal').on('hidden.bs.modal', function (e) {
    alert('Modal is just hidden!');
});

Z oknami modalnymi związane są następujące zdarzenia:

  • show.bs.modal – wywoływane zaraz przed pokazaniem okna modalnego
  • shown.bs.modal – wywoływane zaraz po pokazaniu okna modalnego
  • hide.bs.modal – wywoływane zaraz przed schowaniem okna modalnego
  • hidden.bs.modal – wywoływane zaraz po schowaniu okna modalnego
  • loaded.bs.modal – wywoływane kiedy zdalna zawartość zostanie załadowana do obszaru treści okna modalnego; to zdarzenie następuje tylko jeśli ustawiliśmy ścieżkę do zdalnej zawartości w opcji „remote”

Podsumowanie

Okna modalne Bootstrap to jedną z najbardziej przydatnych wtyczek dla Bootstrap. Opis pozostałych z nich znajdziecie na stronie projektu w sekcji JavaScript Components. Zachęcam do zapoznania się również z nimi i poeksperymentowania. To tyle na dziś i zapraszam do mnie ponownie! :)