Jak dodać plik CSS do strony na WordPressie – prawidłowy sposób

Jak dodać plik CSS do strony na WordPressie

Dołączyć plik CSS do strony na WordPressie – wydawałoby się, że to prosta sprawa. Jednak nawet na forach typu Stack Overflow można znaleźć wskazówki, które utrwalają złe nawyki.

Dzisiaj kompendium wiedzy, jak poprawnie dodajemy pliki CSS do strony na WordPressie: jakich błędów unikać, jaka jest różnica między rejestracją a dodawaniem (kolejkowaniem) pliku CSS, jak kontrolować kolejność i zależności. Wszystko na przykładach.

Dodawanie CSS do motywu WordPressa – filmik

Przykład 1: dołącz plik CSS z Google Fonts

Zadanie: Dodaj plik CSS, umożliwiający korzystanie z wybranego fonta z Google Fonts.

Sprawdź jak wybrać odpowiedniego fonta z Google Fonts, i gdzie znajdziesz odpowiedni plik CSS w zasobach Google’a.

Zanim przejdziemy do rozwiązania, warto wiedzieć jakich błędów unikać, czyli…

Jak nie należy dołączać plików CSS i dlaczego

header.php - nie należy dodawać plików CSS bezpośrednio do pliku header.php
header.php – nie należy dodawać plików CSS bezpośrednio do pliku header.php

Nie należy wstawiać linku do pliku CSS bezpośrednio do pliku header.php naszego motywu.

Dlaczego podany sposób jest niepoprawny? Zadziałać, zadziała, ale… WordPress oficjalnie nie dostaje żadnej informacji o tym pliku. A skoro nic o Twoim pliku nie wie, to nie pomoże Ci:

  • kontrolować kolejności i zależności między plikami
  • umożliwić jego bezbolesne wyrejestrowanie.

Przecież sam sobie ustawiam kolejność, więc o co chodzi?

Nie do końca. Nie możemy zakładać, że ten plik i edycja sekcji <head>, to jedyne miejsce przez które trafiły wszystkie pliku CSS do naszej strony WordPressowej. Pliki CSS mogą trafić do sekcji <head> mimo, że kod, który je wstawia umieszczony jest w innym miejscu w motywie. Pliki CSS mogą pochodzić też z wtyczek, z samego WordPressa. Skąd wiesz, gdzie trafi Twój? Za jakimś plikiem czy przed? I którym?

A poza tym jakie to ma znaczenie… Czy przed czy po…

Kolejność plików CSS  nie musi, ale może mieć znaczenie. Jeśli znasz CSS, wiesz, że w przypadku reguł o takiej samej mocy wygra ta, która pochodzi z pliku, który został dołączony jako ostatni. Zakładając oczywiście, że obie siedzą w plikach.

Zerknij do drugiej części, a zobaczysz praktyczny przykład.

Po co miałbym chcieć wyrejestrowywać plik CSS?

Choćby po to, żeby zastąpić go własną wersją. Dajmy na to kupiłeś motyw na theme stocku, reguły sterujące wyglądem na urządzeniach mobilnych są zebrane w osobnym pliku CSS. WordPress daje ci możliwość wyrejestrowania takiego pliku i zastąpienia go własną, zmodyfikowaną wersją. I to bez zmiany plików motywu oryginalnego!

Zatem korzystajmy z tych dobrodziejstw WordPressa! A jak?

Funkcja wp_enqueue_style – prawidłowy sposób dołączania plików CSS do WordPressa

Do dołączania plików CSS do strony na WordPressie używaj funkcji wp_enqueue_style.

wp_enqueue_style( 
  string $handle, 
  string $src = '', 
  array $deps = array(), 
  string|bool|null $ver = false, 
  string $media = 'all' )

Co robi ta funkcja: rejestruje i dołącza plik CSS do strony. Po angielsku zamiast „dodanie” mówi się, że następuje jego „kolejkowanie” (od słowa enqueue).

Uwaga: Rejestracja w ramach funkcji wp_enqueue_style nastąpi tylko wówczas, gdy podaliśmy jej drugi parametr czyli source (ścieżkę do pliku CSS lub jego pełen URL). Jeśli funkcja wp_enqueue_style zawiera tylko pierwszy parametr, to plik powinien być wcześniej zarejestrowany za pomocą funkcji wp_register_style.

  • Rejestracja pliku CSS– informujemy WordPressa o danym pliku i będzie on dostępny dla WordPressa pod wskazaną (w pierwszym parametrze – handle) nazwą/identyfikatorem (dosł. uchwyt).
  • Kolejkowanie (ang. enqueue) pliku CSS – to fizyczne dodanie CSS do strony.

Czasami jest sens rozdzielić te dwa procesy (rejestracji i kolejkowania) – jeśli ciekawi cię kiedy to ma sens, zerknij do ostatniego punktu.

Jakie parametry są niezbędne?

W naszym przykładzie, aby dodać plik CSS z Google Fonts wykorzystamy tylko dwa pierwsze parametry:

  • $handle – uchwyt, czyli nazwa, pod którą dodany plik będzie dostępny w WordPressie, gdy będziemy się do niego chcieli odwołać z innych miejsc (np. żeby ustalić zależności czy go wyrejestrować).
  • $src – URL lub ścieżka do pliku CSS.

Po dokładny opis parametrów odsyłam do dokumentacji WordPressa.

 wp_enqueue_style( 
   'generatepress-google-font-lato', 
   "https://fonts.googleapis.com/css?family=Lato&amp;subset=latin-ext");

Gdzie taką funkcję należy wywołać/wstawić?

Fizycznie kod tej funkcji może trafić w różne miejsca w naszym motywie. O wiele istotniejsze jest, jak to się stanie, że docelowo ta funkcja zrobi to, na czym nam zależy, czyli dołączy nasz plik CSS do sekcji head front-endu naszej strony.

W tym celu należy wykorzystać odpowiedni hook WordPressa. Mechanizm hooków w WordPressie pozwala nam wykonać nasz własny kod w momencie, gdy w WordPressie coś konkretnego się dzieje, bez modyfikacji kodu źródłowego WordPressa.

Jak informuje Codex WordPressa, właściwy hook, który należy wykorzystać, aby dołaczyć plik CSS do front-endu naszej strony to wp_enqueue_scripts. Wykorzystajmy go zatem, aby wbić się z naszą rejestracją naszego pliku CSS w odpowiednie miejsce:

function generatepress_child_enqueue_scripts() {
 wp_enqueue_style( 
   'generatepress-google-font-lato', 
   "https://fonts.googleapis.com/css?family=Lato&amp;subset=latin-ext");
}
add_action( 'wp_enqueue_scripts', 'generatepress_child_enqueue_scripts' );

Na filmiku wspominam również o innych hookach dodających pliki CSS. Zauważ, że pliki CSS mogą być używane w innym kontekście – np. na stronie logowania do WordPressa albo w back-endzie.

Powyższy kod możemy teraz dodać do pliku functions.php naszego motywu. Najlepiej zrobić to w tzw. motywie potomnym, żeby nie stracić zmian po aktualizacji motywu oryginalnego do nowszej wersji.

functions.php w motywie potomnym
functions.php w motywie potomnym

Po zapisaniu zmian na stronie i odświeżeniu strony, w podglądzie źródła strony zobaczymy taką linię:

Dodany plik CSS w podglądzie źródła strony
Dodany plik CSS w podglądzie źródła strony

Jak usunąć numer wersji

Jak widać na zrzucie z ekranu powyżej, do ścieżki pliku WordPress dokleił numer wersji. Stało się tak dlatego, że w liście parametrów nie podaliśmy w sposób jawny parametru ustalającego numer wersji i została użyta wartość domyślna – numer wersji WordPressa.

Aby usunąć numer wersji należy nieco zmodyfikować nasz kod:

function generatepress_child_enqueue_scripts() {
 wp_enqueue_style( 'generatepress-google-font-lato',
  "https://fonts.googleapis.com/css?family=Lato&amp;subset=latin-ext",
  array(), 
  null );
}
add_action( 'wp_enqueue_scripts', 'generatepress_child_enqueue_scripts' );

Na filmiku (w minucie 11:52) wyjaśniam dlaczego tak należy to zrobić. W nagraniu jest również wyjaśnione kiedy wersjonowanie może się przydać.

Przykład 2: dołącz plik CSS umieszczony w katalogu motywu

Zadanie: Do katalogu motywu dodaj plik reset.css i wstaw go do strony na WordPressie tak, aby znalazł się przed plikiem styles.css.

Drugi przykład jest ciekawszy i bardziej ambitny. Zwróćmy uwagę, że aby spełnić wszystkie wymogi zadania, musimy wiedzieć jak w WordPressie:

  • odwołać się do pliku umieszczonego w katalogu motywu
  • ustawić zależności (kolejność) między plikami.

Plik reset.css dodaje reguły, które ustawiają style domyślne, aby wyrównać punkt startu pod wszystkie przeglądarki. Dlatego musi się on pojawić przed plikiem głównym motywu (style.css).

Aby to zrobić wykorzystamy parametr $deps funkcji wp_enqueue_style, który pozwala nam ustalić zależności między plikami i tym samym kontrolować kolejność umieszczenia pliku.

Żeby poinformować WordPressa, że plik style.css jest zależny od pliku reset.css i tym samym plik reset.css musi zostać dodany jako pierwszy, można użyć następującego kodu:

function test_theme_scripts() {
	
	wp_enqueue_style( 
		'test-theme-style', 
		get_stylesheet_uri(), 
		array('test-theme-reset') 
	);

	wp_enqueue_style( 
		'test-theme-reset',
		get_stylesheet_directory_uri() . '/reset.css',
		array(),
		null 
	);

}
add_action( 'wp_enqueue_scripts', 'test_theme_scripts' );

  • linia 5: get_stylesheet_uri() – zwróci URI głównego pliku CSS (zwykle style.css) motywu, który jest aktualnie w użyciu. Czyli jeśli używasz motywu potomnego, będzie to URI motywu potomnego. Jeśli używasz tego parametru w motywie rodzica, będzie to URI motywu rodzica.
  • linia 6: ustalamy zależność dodawanego pliku od innego, tu mówimy: ten plik (tu style.css) zależy od pliku o uchwycie test-theme-reset (czyli od reset.css), więc dodaj tamten najpierw.
  • linia 11: get_stylesheet_directory_uri() – zwróci URI katalogu aktywnego motywu, w którym trzymany jest główny plik CSS motywu (zwykle style.css). Operator kropki łączy stringi w PHP, więc do URI katalogu doklejona zostanie nazwa pliku reset.css wraz ze slashem.
  • linia 12: brak zależności – podajemy wartość domyślną, gdyż bez uzupełnienia parametru 3. nie możemy ustawić parametru 4. – wartości dla numeru wersji, którą to wartość w tym przykładzie chcemy zmienić
  • linia 13: nie wklejaj żadnego numeru wersji.

W ten sposób ostatecznie w podglądzie źródła strony zobaczymy:

Plik reset.css w podglądzie źródła strony
Plik reset.css w podglądzie źródła strony

Na filmiku omawiam ten przykład dokładnie.

Kiedy wp_enqueue_style a kiedy para: wp_register_style i wp_enqueue_style

Jak wspomnieliśmy, funkcja wp_enqueue_style jednocześnie rejestruje i dodaje plik CSS do strony. Więc nie za bardzo ma sens dodawanie kodu w poniższy sposób:

wp_register_style( 'my-style', get_template_directory_uri() . '/css/my-style.css' );
wp_enqueue_style( 'my-style' );

czyli najpierw wywołanie funkcji wp_register_style a zaraz po niej wp_enqueue_style.

Powstaje zatem pytanie: po co w ogóle istnieje funkcja wp_register_style, skoro wp_enqueue_style też potrafi rejestrować plik CSS i na dodatek robi dwie rzeczy na raz.

Czasami może się to przydać. Kiedy? Przykład omawiam w końcówce filmiku.

Podsumowanie

Jak widać, prawidłowe dodawanie pliku CSS nie jest trudne, jeśli się rozumie, co się robi i po co się tak robi.

Dodawanie skryptów JavaScript do WordPressa odbywa się na podobnych zasadach, a tam ustawienie kolejności i zależności między plikami ma jeszcze większe znaczenie. Dlatego, jeśli korzystasz z WordPressa, to warto wyrabiać sobie dobre nawyki nawet przy prostych przykładach i unikać drogi na skróty, która tylko z pozoru jest szybszym i mniej kłopotliwym rozwiązaniem.

Jeśli mówisz sobie:

Matko jedyna, nie chce mi się robić całej tej analizy różnych funkcji, ich parametrów, hooków i co tam macie jeszcze w tym WordPressie. Ja potrzebuję dodać tylko jedną głupią linijkę!

to nie zdziw się, jeśli potem więcej czasu stracisz na rozkminianie dlaczego coś działa nie tak, jakbyś oczekiwał.

14 komentarzy do “Jak dodać plik CSS do strony na WordPressie – prawidłowy sposób”

        1. Dzięki Marcin. Gotowe. Chwilkę mi to zajęło, bo musiałam zmienić wszystkie zrzuty ekranu, żeby było spójnie.

  1. No i fajnie 😉
    Można by jeszcze przy okazji wspomnieć o deregister i dequeue -wszak czasem lepiej coś usunąć lub podmienić zamiast multiplikować i nadpisywać.

    1. Słusznie! Okazuje się, że wyrejestrowanie to dłuższy temat, bo plik functions.php motywu potomnego wykonuje się przed functions.php z motywu rodzica i nie bardzo ma sens wyrejestrowywać coś, co dopiero za chwilę zostanie zarejestrowane, więc robię osobny wpis i filmik jak to ogarnąć – przy okazji będzie dobry moment, żeby wspomnieć o parametrze priority dla funkcji add_action na jakimś konkretnym przykładzie, więc dzięki za sugestię Paweł! Jak ten nowy wpis i filmik będzie gotowy, to tutaj wstawię odpowiednią wzmiankę o tych funkcjach z linkiem do tamtego wpisu.

      1. Oj, ma sens i własnie odpowiedziałaś – dzięki priorytetom.
        W tym własnie cały urok akcji i filtrów, nawet z poziomu wtyczki można sobie wpływać na działanie motywu, który nie został jeszcze nawet załadowany.

    1. Hej, kurczę niefortunnie nazwałam plik. Bo ja w przykładzie użyłam motywu wygenerowanego na bazie underscore i plik reset.css utworzyłam wycinając z pliku style.css underscore’a reguły normalizujące i zapisując je pod nazwą reset.css. Były one opatrzone komentarzem „Normalizing styles have been helped along thanks to the fine work of Nicolas Gallagher and Jonathan Neal http://necolas.github.io/normalize.css/” więc to nie był taki reset jak się robiło kiedyś, np. z tego słynnego pliku Erica Meyera tylko już ten bardziej „współczesny” i zalecany teraz, że tak powiem. Świetne pytanie i cieszy mnie, że zwracasz uwagi na takie szczegóły, bo okazują się znaczące. Dzięki!

  2. Hej Aga,
    Dzięki za dobry tekst!

    Przy tej okazji można też dodać o usuwaniu wersji poprzez `wp_enqueue_script` przy plikach statycznych, co jest czasem pożądane, a czasem chcemy po prostu mieć nad nim kontrolę.

    Np. dzięki

    wp_enqueue_script('oxfam_js_cookie', 'https://cdnjs.cloudflare.com/ajax/libs/js-cookie/2.1.0/js.cookie.min.js', array(), null, true);

    dostaniemy

    1. Mariusz, chyba obcięło kawałek Twojego kodu, bo piszesz: „dostaniemy” i dalej nie ma nic. Spróbuj może otoczyć go w znaczniki code, czyli <code></code> Ja jeden przykład z usuwaniem wersji mam, ale dotyczy rejestracji plików CSS. O plikach JS planuję napisać osobny artykuł (albo mini serię), bo to zdecydowanie ciekawy temat. Dzięki za komentarz.

  3. Fajny artykuł, ale stworzyłem plugin, gdzie są foldery css, js i plik php. Dodałem do pliku php kod wp_enqueue_style i plugin_url(tu ścieżka) i nie działają mi style w pluginie admina. Tylko same błędy lub ich brak. w folderze css jest style.css a odwoływałem się ./css/style.css.

Skomentuj Aga Anuluj pisanie odpowiedzi

Twój adres e-mail nie zostanie opublikowany.