WP-DOC

Pisanie motywu

02.02 Dołączanie plików – functions.php

Ostatnia modyfikacja: 07.04.2021

Utworzenie pliku functions.php

Zanim dołączamy plik css oraz font od Google, należy utworzyć plik o nazwie functions.php w folderze motywu wpnauka. W pliku tym będziemy dodawać funkcje PHP, które będą działać na naszej stronie. Najczęściej będą to funkcje WordPress rozszerzające możliwości naszego motywu. Dlaczego funkcje WordPress musimy dodawać sami? Dlatego, że WordPress posiada ich bardzo dużo i nie wszystkie zawsze będą nam potrzebne w każdym motywie. Dodatkowo, niektóre funkcje wymagają wprowadzenia odpowiednich argumentów.

Tworzenie funkcji do kolejkowania

W WordPress, mówi się o kolejkowaniu skryptów (js) czy plików css, które mają pojawić się na stronie. Jest to obecnie zalecany sposób łączenia plików css, js z motywem. Do pliku functions.php dodajmy zatem pierwszą funkcję w języku PHP. Funkcja ta może posiadać dowolną nazwę. W kodzie pozwoliłem dodać sobie od razu komentarz, gdyż na samym końcu pracy tego typu funkcji trochę się nazbiera.

functions.php – utworzenie funkcji do kolejkowania plików css, js

<?php
// Dołączanie plików CSS/JS
function wpnauka_scripts() {
 
}
// ------------------------------------------------------------
?>

Do uruchomienia funkcji musimy dodać akcję, w której zdefiniujemy dwa parametry. Pierwszy to nazwa funkcji WordPress, do której się podłączamy, drugi parametr to funkcja do wywołania. Akcję taką wykonujemy za pomocą add_action(), jak na listingu niżej.

functions.php – dodanie akcji

<?php
// Dołączanie plików CSS/JS
function wpnauka_scripts() {
 
}
add_action('wp_enqueue_scripts', 'wpnauka_scripts');
// ------------------------------------------------------------

W tym przykładzie funkcja wp_enqueue_scripts, załaduje pliki css, js czy font od Google do motywu.

Musisz wiedzieć, że w WordPress istnieją dwa rodzaje zaczepów. Akcje add_action() ora filtry add_filter(). Różnice między nimi wyjaśniam na końcu tego postu.

Dołączanie arkusza styli

Do dołączenia pliku css należy posłużyć się funkcją WordPress wp_enqueue_style(). Funkcja ta przyjmuje kilka parametrów, które są przedstawione na listingu niżej

wp_enqueue_style() – parametry funkcji

wp_enqueue_style( 
    $handle, // Nazwa, którą nadajemy dla arkusza, musi być unikalna.
    $src, // Ścieżka do arkusza stylu, tylko ten i pierwszy parametr jest obowiązkowy.
    $deps, // Jeżeli akrusz stylów jest powiązany z innym arkuszem to podajemy z jakim. Wartość domyślna tablica.
    $ver, // Wersja arkusza stylów. Wartość false oznacza wersję wydania WordPress, wartość null, żadna wersja nie zostanie dodana.
    $media // Możliwe wartości to all, print, screen, lub zdefiniowana przez media queries, domyślnie all.
);

Do wskazania ścieżki pliku style.css, który znajduje się w głównym folderze motywu, można posłużyć się funkcją get_stylesheet_uri(). Funkcja ta zwraca adres url wraz z nazwą pliku styli. Funkcję wp_enqueue_style(), należy uzupełnić jak na listingu niżej.

wp_enqueue_style() – uzupełnienie funkcji w parametry dla motywu

wp_enqueue_style('wpnauka-style', get_stylesheet_uri(), array(), null, 'all');

Powyższą funkcję możemy skopiować do funkcji wpnauka_scripts(). Całość będzie wyglądać jak na listingu niżej.

functions.php – uzupełnienie funkcji wpdoc_scripts()

<?php
// Dołączanie plików CSS/JS
function wpnauka_scripts() {
    wp_enqueue_style('wpnauka-style', get_stylesheet_uri(), array(), null, 'all');
}
add_action('wp_enqueue_scripts', 'wpnauka_scripts');
// ------------------------------------------------------------
?>

W tym momencie nasz plik style.css, zostanie załadowany a nasza strona nabierze „kształtów”. Teraz powinna wyglądać jak na zdjęciu niżej.

Widok strony internetowej WP-NAUKA
Strona po podłączeniu pliku style.css.

Przy artykułach z lewej strony powinny znajdować się zdjęcia. I tu po raz kolejny okazuje się, że ścieżki, tym razem do grafik, podane z kodzie html są nie wystarczające. Ale tym zajmiemy się później.

Dodanie fontu od Google

Funkcje użyte do dodania pliku ze stylami, będą dokładnie takie same, jak do dodania fontu od Google. Z tą różnicą, że podamy tylko pierwsze dwa parametry, gdyż w tym przypadku reszta jest zbędna. Zatem funkcja wpdoc_scripts() będzie wyglądać jak na listingu niżej.

functions.php – dodanie fontu od Googli.

<?php
// Dołączanie plików CSS/JS
function wpnauka_scripts() {
    wp_enqueue_style('wpnauka-font', 'https://fonts.googleapis.com/css?family=Barlow:400,400i,700,700i&display=swap&subset=latin-ext');
    wp_enqueue_style('wpnauka-style', get_stylesheet_uri(), array(), null, 'all');
}
add_action('wp_enqueue_scripts', 'wpnauka_scripts');
// ------------------------------------------------------------
?>

Mając zdefiniowane połączenie z plikiem style.css oraz podłączony font od Google, w pliku header.php, należy usunąć linie kodu z poniższego listingu.

Dodanie pliku js

Motyw, na którym pracujemy nie zawiera żadnego pliku js, ale warto zapoznać się w jaki sposób dodaje się pliki js do motywu WordPress. Korzystamy z tej samej funkcji co w przypadku css, czyli wp_enqueue_style(). Dodatkowo warto skorzystać z funkcji get_template_directory_uri(), która wskazuje na folder bieżącego motywu. Dla przykładu, gdy strona jest pod adresem www.xyz.pl, to funkcja ta pobierze adres www.xyz.pl/wp-content/themes/folder-motywu co znacznie skróci to adres w kodzie PHP. Jeżeli posiadamy certyfikat SSL, adres zostanie poprzedzony przedrostkiem https://. Kiedy nie posiadamy SSL, adres zostanie poprzedzony przedrostkiem http://.

Załóżmy sytuację, że plik script.js znajduje się w folderze o nazwie js. Wówczas pełna ścieżka do pliku scritp.js przy użyciu get_template_directory_uri(), będzie wyglądać jak na listingu niżej. Oczywiście całość należy podpiąć do akcji add_action().

Przykładowe dodanie pliku js do motywu

 wp_enqueue_script('unikalna-nazwa', get_template_directory_uri() . '/js/script.js', array(), '1.0', true);

// Poniżej url do pliku, kiedy ten znajduje się w folderze głównym motywu
 wp_enqueue_script('unikalna-nazwa', get_template_directory_uri() . '/script.js', array(), '1.0', true);

Pierwsze cztery parametry są identyczne jak w przypadku dołączenia pliku css. Natomiast ostatni parametr w przypadku dołączenia pliku js, przyjmuje dwa parametry true lub false. Jeżęli wpiszemy wartość true, skrypt zostanie dodany przed zamknięciem znacznika body. Wartość false, oznacza, że skrypt zostanie dodany przed znacznikiem zamykającym head.

Numer wersji dołączanego pliku

Numer wersji może przyjąć jeden z trzech argumentów:

  • Wersja, którą podamy sami. Najczęściej jest to numer, jednak parametr ten podajemy jako ciąg znaków – string;
  • false – wówczas numer wersji pliku będzie taki sam jak numer wersji WordPress;
  • null – żaden numer nie zostanie dodany

W poniższym przykładzie dołączany plik CSS posiada wersje o numerze 1.3. Ten sam mechanizm można zastosować dla pliku JS.

Przykładowa wersja głównego pliku CSS dla motywu z numerem wersji

wp_enqueue_style('wpnauka-style', get_stylesheet_uri(), array(), '1.3', 'all');

Numer wersji dołączany jest do adresu pliku. W przypadku zmiany numeru wersji, plik zostanie wczytany na nowo z pominięciem pamięci podręcznej przeglądarki. Wówczas mamy pewność, że każdemu użytkownikowi po odświeżeniu strony, zostanie załadowany nowy plik CSS. Ten sama mechanizm dotyczy również plików JS.

Za każdym razem, kiedy zaktualizujemy plik CSS lub JS w pliku functions.php musimy zmienić numer wersji, aby mieć pewność, że każdej osobie odwiedzającej naszą stronę, zostanie załadowany nowy plik CSS lub JS. Za pomocą funkcji PHP filemtime(), która zwraca datę edycji pliku, możemy proces numeru wersji zautomatyzować. Funkcja ta zwróci za każdym razem inną datę modyfikacji pliku, kiedy ten ulegnie zmianie (ponowne wysłanie pliku na serwer lub jego edycja). Da to efekt automatycznej zmiany wersji dołączanego pliku.

Użycie funkcji filemtime() dla pliku CSS w celu automatycznej zmiany wersji

wp_enqueue_style('wpnauka-style', get_stylesheet_uri(), array(), filemtime(get_stylesheet_directory().'/style.css'), 'all');

Różnica między add_action() a add_filter()

Akcje

Akcja pozwala wywołać funkcję w określonym momencie ładowania WordPress, na przykład przy całkowitym załadowaniu. Zazwyczaj akcje dodają nową funkcjonalność lub rozszerzają obecne funkcje. Tego typu funkcję należy napisać samemu.

Przykładem zaczepu akcji jest dodanie arkusza styli lub pliku js, co zostało opisane wyżej.

Filtry

Zaczep filtru pozwala na modyfikację danych zwracanych przez inne funkcje najczęściej WordPress. W przeciwieństwie do zaczepu akcji, filtry muszą przyjmować jakieś parametry oraz muszą zwracać zmodyfikowane parametry wejściowe. Dokładnie tak samo jak w akcjach i tu odpowiednią funkcję musimy napisać sami.

Przykład zaczepu add_filter()

function num_charest() {
    return 20;
}
add_filter('excerpt_length', 'num_charest');

Ten filtr modyfikuje funkcję WordPress excerpt_lenght(), która odpowiada za wyświetlenie ilości słów „zajawki” posta. Z godnie z powyższym opisem funkcja pobiera (domyślnie jest to 55 słów), modyfikuje (funkcję WordPress) i zwraca wartość liczbową, która odpowiada za ilość słów „zajawki”.

Czytaj dalej…

02.03 Ozdobna grafika w motywie

KOMENTARZE

Jeżeli masz pytanie lub sugestie dotyczącą artykułu to napisz komentarz. Wartościowe komentarze zostaną umieszczone jako opinie warte uwagi.

Napisz komentarz

Wszystkie pola są obowiązkowe. E-mail nie będzie udostępniony, ani wykorzystywany do rozsyłania wiadomości reklamowych.

Jeszcze nikt nie napisał komentarza.