Dziś miałem opublikować wpis pokazujący jak w przypadku sklepu internetowego opartego o WooCommerce (WordPress) dodać załącznik do wiadomości e-mail z potwierdzeniem zamówienia. Powód nie jest przykładowy – 25 grudnia w życie wejdą nowe przepisy, które przynosi Ustawa o prawach konsumenta, a wraz z nimi nowe obowiązki informacyjne… Po chwili namysłu stwierdziłem, że zanim wspomniany wpis trafi do publikacji muszę nadrobić jeszcze jeden temat – jak dodać do strony opartej o WordPressa własny kod, i o tym właśnie dziś będzie.

Własny kod w WordPressie

Przedstawię 2 chyba najpopularniejsze sposoby na dodanie własnego kodu do strony opartej o system CMS WordPress.

• Własny kod w pliku functions.php
• Własna wtyczka

Oczywiście w obu przypadkach kod to PHP, choć jak w przypadku PHP można dołączyć i inne języki/elementy (np. HTML, JavaScript, CSS).

Plik functions.php

Najprostszy sposób to dodanie własnego kodu do pliku functions.php, który znajduje się w katalogu motywu potomnego. To – motyw potomny – jest właściwie warunek konieczny, by zacząć, bo inaczej wszelkie zmiany zostaną nadpisane przy najbliższej aktualizacji motywu.

Struktura (czystego pliku, z motywu potomnego) wygląda tak:

<?php

/* Swój kod wprowadź poniżej: */

[KOD]

/* Swój kod wprowadź powyżej */

Załóżmy, że chcemy dodać do naszej strony taki kod:

echo "Jakiś tekst";

W takim przypadku cały plik functions.php będzie wyglądał tak:

<?php

/* Swój kod wprowadź poniżej: */

echo "Przykładowy tekst";

/* Swój kod wprowadź powyżej */

Przykład może nie jest jakiś specjalnie wartościowy – spowoduje wyświetlenie tekstu „Przykładowy tekst” na górze strony, ale jego celem jest pokazanie, jak można do tego pliku dodać inny, już bardziej rozbudowany kod.

Własna wtyczka do WordPressa

Kolejna możliwość to przygotowanie własnej wtyczki – na potrzeby tego poradnika pokaże najprostszy sposób na przygotowanie wtyczki i dodanie jej do WordPressa. Nie będę się skupiał na dodawaniu wtyczki do publicznego repozytorium WordPress.org, na to może przyjdzie czas niebawem… :-)

Zasada jest podobna jak w przypadku pliku functions.php, z tym że tworzymy nowy plik o wybranej przez nas nazwie, np.:

nazwa_wtyczki.php

Struktura pliku wtyczki wygląda tak:

<?php
/*
 * Plugin Name: Moja pierwsza wtyczka
 * Plugin URI: https://webinsider.pl
 * Description: Przykładowa wtyczka do WordPressa
 * Author: Patryk
 * Author URI: https://webinsider.pl
 * Version: 1.0.1
 * License: GPLv2 or later
 * License URI: http://www.gnu.org/licenses/gpl-2.0.html
*/

if (!defined('ABSPATH')) exit;

/* Swój kod wprowadź poniżej: */

[KOD]

/* Swój kod wprowadź powyżej */

Załóżmy, że i tym razem chcemy dodać do naszej strony taki kod:

echo "Przykładowy tekst";

W takim przypadku cały plik wtyczki będzie wyglądał tak:

<?php
/*
 * Plugin Name: Moja pierwsza wtyczka
 * Plugin URI: https://webinsider.pl
 * Description: Przykładowa wtyczka do WordPressa
 * Author: Patryk
 * Author URI: https://webinsider.pl
 * Version: 1.0.1
 * License: GPLv2 or later
 * License URI: http://www.gnu.org/licenses/gpl-2.0.html
*/

if (!defined('ABSPATH')) exit;

/* Swój kod wprowadź poniżej: */

echo "Przykładowy tekst";

/* Swój kod wprowadź powyżej */

Tak zapisany plik kopiujemy do katalogu:

/wp-content/plugins/

I już możemy wtyczkę aktywować w panelu WordPressa:

Oczywiście – jak wcześniej – jest to najprostszy przykład, który ma pokazać tylko mechanizm, a kod użyty kod zależy od Waszych potrzeb.

Plik wtyczki można również umieścić w katalogu, np.:

nazwa_wtyczki/nazwa_wtyczki.php

Przydatne, zwłaszcza gdy oprócz kodu PHP planujemy również wykorzystać inne elementy, np. pliki graficzne.

Kod w pliku functions.php, czy wtyczka?

W tym momencie może pojawić się pytanie, z której metody lepiej skorzystać – kodu w pliku functions.php motywu potomnego, czy własnej wtyczki?

Teoretycznie w pliku functions.php powinno iść tylko to, co ma bezpośredni związek z danym motywem, a wszystko inne do wtyczki. Głównie chodzi o to, by przy zmianie motywu nie utracić wszystkich modyfikacji, a jednocześnie automatycznie wyłączyć te, które są związane ze starym motywem, czyli najpewniej już niepotrzebne.

Tyle teorii, bo jak często zmienia się motyw, na działającej stronie? Raczej dość rzadko. Do tego podczas zmiany i tak dobra praktyka nakazuje zrobić motyw potomny, a więc przy okazji można skopiować kod z pliku functions.php starego motywu. Dobrze jednak w takim przypadku stosować komentarze, by opisać, do czego dany kod, oraz najlepiej trzymać podobny tematycznie kod obok siebie.

Ja najczęściej większość modyfikacji wrzucam do pliku functions.php, a do wtyczek przenoszę głównie większe, bardziej rozbudowane modyfikacje, oraz takie, które chcę, by można było dość swobodnie włączać i wyłączać, bo wtedy wtyczka jest dużo wygodniejsza, niż edycja pliku PHP.

WordPress hooks, czyli akcje i filtry

To, co pozwala w pełni wykorzystać możliwości, jakie daje możliwość umieszczenia i wykonania własnego kodu w ramach WordPressa to tzw. haki w WordPressie. Nawet zaryzykuje stwierdzenie, że w dużej mierze to właśnie ten element miał duże znaczenie w sukcesie, jaki odniosła ta platforma. To właśnie dzięki hakom możemy zdecydować co, gdzie i kiedy ma się wykonać.

Ogólnie wyróżniamy akcje i filtry, które na pierwszy rzut okaz mogą wydawać się podobne, a wręcz identyczne, ale ich działanie (cel) jest inny:

• Akcje – wykonują konkretne operacje w konkretnym momencie
• Filtry – wykonują operacje na danych (np. treści)

Opis wszystkich akcji i filtrów najdziecie na stronie WordPress Codex, a konkretnie:

• Plugin API/Filtry
• Plugin API/Akcje

Jak korzystać

Z haków (filtrów i akcji) w WordPressie odwołujemy się za pomocą takich kodów:

add_action ('nazwa_haka','nazwa-funkcji',$priorytet,$ilość_argumentów);
add_filter ('nazwa_haka','nazwa-funkcji',$priorytet,$ilość_argumentów);

Kilka (prostych) przykładów

Jeden z prostszych, a zarazem przydatnych kodów jest coś takiego:

add_filter('widget_text','do_shortcode');

Wydaje się, że niby nic takiego tu nie ma, a właśnie dodaliśmy obsługę shortcode do widgetów.

Inny przykład to wykonanie konkretnej (zdefiniowanej) funkcji w panelu administracyjnym WordPressa:

add_action('admin_head','nazwa_funkcji');

A całość – razem z funkcją – będzie wyglądała np. tak:

function nazwa_funkcji() {
    echo "Przykładowy tekst";
}
add_action('admin_head','nazwa_funkcji');

Oczywiście to tylko zarys wykorzystania haków (API) w WordPressie, może kiedyś jeszcze powrócę do tematu – ale raczej będzie to w formie konkretnych przykładów, rozwiązujących konkretne problemy, niż „wykłady z teorii haków” ;-)