WPBakery: własny widget z oknem modal (Bootstrap)
Jak stworzyć własny widget WPBakery, który wyświetla okno modal (pop-up) z użyciem Bootstrapa: parametry vc_map, kod widgetu, niepowtarzalne ID i zabezpieczenie danych.
WordPress
Pokażemy, jak stworzyć własny widget WPBakery, który wyświetla modal (okno pop-up). Wyzwalaczem okna jest blok z obrazem i tytułem. Po najechaniu kursorem obraz zmienia się na drugi, a po kliknięciu otwiera się okno z treścią z edytora WordPress. Okno budujemy na gotowych klasach Bootstrapa.
WPBakery ma wbudowany element do dodawania modali, ale w naszym przypadku jego właściwości uniemożliwiały poprawne działanie. Dlatego napisaliśmy własny widget.
Zrzuty ekranu pokazują polski panel administracyjny. Nazwy pól i teksty w kodzie zostają w takiej postaci, w jakiej je podajemy.
Wymagania
- Motyw WordPress z Bootstrapem 4. Kod korzysta z atrybutów
data-toggle,data-targetidata-dismissoraz z klas Bootstrapa 4. Modal Bootstrapa 4 wymaga też jQuery. W Bootstrapie 5 atrybuty mają inne nazwy (data-bs-toggle,data-bs-target,data-bs-dismiss), a jQuery nie jest potrzebne. - Wtyczka z widgetami WPBakery. Własne widgety dodajemy w osobnej wtyczce. Jej tworzenie opisujemy w artykułach:
- Podstawowa wiedza o Bootstrapie i jego komponencie modal:
- Bootstrap – co to jest i czy warto go używać,
- dokumentacja komponentu Modal w Bootstrapie 4. Stąd bierzemy kod okna.
Bootstrapa można dołączyć do motywu samodzielnie albo użyć motywu startowego, który już go zawiera, na przykład WP Bootstrap Starter.
Dodanie widgetu do wtyczki
W folderze widgets wtyczki tworzymy plik modal.php. W pliku głównym main.php dopisujemy go do funkcji vc_redo_widgets():
require_once __DIR__ . '/widgets/modal.php';
Szkielet widgetu
Zaczynamy od pustego szkieletu widgetu: nazwy, kategorii i podstawowych właściwości.
<?php
if ( ! defined( 'ABSPATH' ) ) {
die( '-1' );
}
class WPBakeryShortCode_modal extends WPBakeryShortCode {
protected function content( $atts, $content = null ) {
$atts = shortcode_atts( array(), $atts );
ob_start();
?>
<!-- HTML DESIGN HERE -->
<!-- HTML END DESIGN HERE -->
<?php
return ob_get_clean();
}
}
vc_map( array(
'name' => __( 'Modal', 'redo-jscomposer-additional' ),
'base' => 'modal',
'category' => __( 'REDO JSComposer Additional', 'redo-jscomposer-additional' ),
'description' => __( 'Display modal', 'redo-jscomposer-additional' ),
'icon' => plugin_dir_url( __FILE__ ) . '../images/int-banner.png',
'params' => array(),
) );
W szkielecie wykonaliśmy podstawowe kroki:
- zabezpieczyliśmy plik stałą ABSPATH,
- utworzyliśmy klasę dziedziczącą po
WPBakeryShortCode. Jej nazwa toWPBakeryShortCode_i wartośćbasezvc_map(), - zarejestrowaliśmy widget funkcją
vc_map(). Podajemy w niej nazwę, kategorię, opis, ikonę i tablicę parametrów.
Parametry widgetu
W przykładach Bootstrapa wyzwalaczem modala jest przycisk. My chcemy, aby wyzwalaczem był div o stałych rozmiarach, zawierający obraz i tytuł modala. Po najechaniu kursorem obraz zmienia się na drugi. Potrzebujemy więc w tablicy params czterech pól:
- obraz przycisku (
attach_image), - obraz przycisku po najechaniu kursorem (
attach_image), - tytuł modala (
textfield), - treść modala (
textarea_html).
Typ textarea_html pozwala wpisać treść modala we wbudowanym edytorze WordPress (WYSIWYG). Wartość takiego pola trafia do zmiennej $content. Widget może mieć tylko jedno pole tego typu, a jego param_name musi mieć wartość content.
Pełna funkcja vc_map() z parametrami wygląda tak:
vc_map( array(
'name' => __( 'Modal', 'redo-jscomposer-additional' ),
'base' => 'modal',
'category' => __( 'REDO JSComposer Additional', 'redo-jscomposer-additional' ),
'description' => __( 'Display modal', 'redo-jscomposer-additional' ),
'icon' => plugin_dir_url( __FILE__ ) . '../images/int-banner.png',
'params' => array(
array(
'type' => 'attach_image',
'heading' => __( 'Modal button image', 'redo-jscomposer-additional' ),
'param_name' => 'btn_image',
),
array(
'type' => 'attach_image',
'heading' => __( 'Modal button image on hover', 'redo-jscomposer-additional' ),
'param_name' => 'btn_image_hover',
),
array(
'type' => 'textfield',
'holder' => 'div',
'heading' => __( 'Modal title', 'redo-jscomposer-additional' ),
'param_name' => 'modal_title',
),
array(
'type' => 'textarea_html',
'heading' => __( 'Modal description', 'redo-jscomposer-additional' ),
'param_name' => 'content',
),
),
) );
Uwaga: nie przekazujemy pustego tekstu do funkcji __(). Dla pustego ciągu zwraca ona nagłówek pliku tłumaczeń, a nie pusty tekst. Dlatego w parametrach pomijamy pole value.
Widok widgetu
Zaczynamy od pobrania atrybutów. Funkcja shortcode_atts() uzupełnia brakujące atrybuty wartościami domyślnymi. Zamiast extract() zapisujemy wynik w tablicy $atts. Dzięki temu widać, skąd pochodzi każda zmienna.
Każdy modal na stronie musi mieć własne, niepowtarzalne ID, bo wyzwalacz wskazuje swój modal przez data-target. Takie ID generujemy funkcją wp_unique_id(). Dzięki temu modale mogą używać tych samych obrazów. ID służy też jako prefiks klasy obrazu przycisku, dzięki czemu każdy wyzwalacz może mieć własne tło.
Adresy obrazów pobieramy funkcją wp_get_attachment_url(). ID obrazu z parametru przepuszczamy przez absint().
$atts = shortcode_atts( array(
'btn_image' => '',
'btn_image_hover' => '',
'modal_title' => '',
), $atts );
$modal_id = wp_unique_id( 'modal-' );
$modal_title = $atts['modal_title'];
$btn_image_url = $atts['btn_image'] ? wp_get_attachment_url( absint( $atts['btn_image'] ) ) : '';
$btn_image_hover_url = $atts['btn_image_hover'] ? wp_get_attachment_url( absint( $atts['btn_image_hover'] ) ) : '';
Zmienna $content jest dostępna domyślnie jako drugi argument metody content(). Zawiera treść z pola textarea_html.
Wyzwalacz modala
Wyzwalaczem jest div z atrybutami data-toggle="modal" i data-target. W data-target podajemy ID modala z # na początku. Wartości wypisujemy przez esc_attr(), a tytuł przez esc_html().
<div class="modal-button" data-toggle="modal" data-target="#<?php echo esc_attr( $modal_id ); ?>">
<div class="btn-image <?php echo esc_attr( $modal_id ); ?>-image"></div>
<div class="btn-title">
<?php echo esc_html( $modal_title ); ?>
</div>
</div>
Uwaga: div nie jest elementem aktywnym dla klawiatury. Jeśli modal ma być dostępny bez myszy, zamiast div warto użyć elementu a albo button i dostosuj style.
Style CSS zmieniające obraz po najechaniu kursorem generujemy z adresów obrazów. Adresy zabezpieczamy funkcją esc_url(). W tym przykładzie wstawiamy style bezpośrednio w widgecie. W większym projekcie lepiej przenieść stałą część stylów do pliku CSS motywu, a w widgecie zostawić tylko adresy obrazów.
<style>
.<?php echo esc_attr( $modal_id ); ?>-image {
background: url('<?php echo esc_url( $btn_image_url ); ?>');
}
.modal-button:hover .<?php echo esc_attr( $modal_id ); ?>-image {
background: url('<?php echo esc_url( $btn_image_hover_url ); ?>');
}
</style>
Treść modala
Korzystamy z gotowego kodu modala z Bootstrapa. Zmieniamy w nim ID, aby każdy modal miał inne, i dodajemy aria-labelledby wskazujące nagłówek modala. W div o klasie modal-body wypisujemy zmienną $content.
Ikonę zamknięcia ładujemy z folderu images wtyczki. Treść z pola textarea_html przepuszczamy przez funkcję WPBakery wpb_js_remove_wpautop(). Usuwa ona zbędne akapity i wykonuje shortcode’y z wnętrza treści. WordPress filtruje treść wpisu przy zapisie, więc nie dodajemy drugiego filtra, który usunąłby elementy zagnieżdżonych shortcode’ów.
<div class="modal fade" id="<?php echo esc_attr( $modal_id ); ?>" tabindex="-1" role="dialog" aria-labelledby="<?php echo esc_attr( $modal_id ); ?>-title" aria-hidden="true">
<div class="modal-dialog modal-dialog-centered" role="document">
<div class="modal-content">
<div class="modal-header">
<h2 class="modal-title" id="<?php echo esc_attr( $modal_id ); ?>-title"><?php echo esc_html( $modal_title ); ?></h2>
<button type="button" class="b-close close" data-dismiss="modal" aria-label="Close">
<img src="<?php echo esc_url( plugin_dir_url( __FILE__ ) . '../images/cross.png' ); ?>" alt="">
</button>
</div>
<div class="modal-body">
<div class="modal-description">
<?php echo wpb_js_remove_wpautop( $content, true ); ?>
</div>
</div>
</div>
</div>
</div>
Pełny kod widgetu
Poniżej cały plik modal.php.
<?php
if ( ! defined( 'ABSPATH' ) ) {
die( '-1' );
}
class WPBakeryShortCode_modal extends WPBakeryShortCode {
protected function content( $atts, $content = null ) {
$atts = shortcode_atts( array(
'btn_image' => '',
'btn_image_hover' => '',
'modal_title' => '',
), $atts );
$modal_id = wp_unique_id( 'modal-' );
$modal_title = $atts['modal_title'];
$btn_image_url = $atts['btn_image'] ? wp_get_attachment_url( absint( $atts['btn_image'] ) ) : '';
$btn_image_hover_url = $atts['btn_image_hover'] ? wp_get_attachment_url( absint( $atts['btn_image_hover'] ) ) : '';
ob_start();
?>
<style>
.<?php echo esc_attr( $modal_id ); ?>-image {
background: url('<?php echo esc_url( $btn_image_url ); ?>');
}
.modal-button:hover .<?php echo esc_attr( $modal_id ); ?>-image {
background: url('<?php echo esc_url( $btn_image_hover_url ); ?>');
}
</style>
<!-- HTML DESIGN HERE -->
<div class="modal-button" data-toggle="modal" data-target="#<?php echo esc_attr( $modal_id ); ?>">
<div class="btn-image <?php echo esc_attr( $modal_id ); ?>-image"></div>
<div class="btn-title">
<?php echo esc_html( $modal_title ); ?>
</div>
</div>
<div class="modal fade" id="<?php echo esc_attr( $modal_id ); ?>" tabindex="-1" role="dialog" aria-labelledby="<?php echo esc_attr( $modal_id ); ?>-title" aria-hidden="true">
<div class="modal-dialog modal-dialog-centered" role="document">
<div class="modal-content">
<div class="modal-header">
<h2 class="modal-title" id="<?php echo esc_attr( $modal_id ); ?>-title"><?php echo esc_html( $modal_title ); ?></h2>
<button type="button" class="b-close close" data-dismiss="modal" aria-label="Close">
<img src="<?php echo esc_url( plugin_dir_url( __FILE__ ) . '../images/cross.png' ); ?>" alt="">
</button>
</div>
<div class="modal-body">
<div class="modal-description">
<?php echo wpb_js_remove_wpautop( $content, true ); ?>
</div>
</div>
</div>
</div>
</div>
<!-- HTML END DESIGN HERE -->
<?php
return ob_get_clean();
}
}
vc_map( array(
'name' => __( 'Modal', 'redo-jscomposer-additional' ),
'base' => 'modal',
'category' => __( 'REDO JSComposer Additional', 'redo-jscomposer-additional' ),
'description' => __( 'Display modal', 'redo-jscomposer-additional' ),
'icon' => plugin_dir_url( __FILE__ ) . '../images/int-banner.png',
'params' => array(
array(
'type' => 'attach_image',
'heading' => __( 'Modal button image', 'redo-jscomposer-additional' ),
'param_name' => 'btn_image',
),
array(
'type' => 'attach_image',
'heading' => __( 'Modal button image on hover', 'redo-jscomposer-additional' ),
'param_name' => 'btn_image_hover',
),
array(
'type' => 'textfield',
'holder' => 'div',
'heading' => __( 'Modal title', 'redo-jscomposer-additional' ),
'param_name' => 'modal_title',
),
array(
'type' => 'textarea_html',
'heading' => __( 'Modal description', 'redo-jscomposer-additional' ),
'param_name' => 'content',
),
),
) );
Efekt
Okno dodawania widgetu w WPBakery wygląda tak:

Po dodaniu stylów CSS dla klas modal-button, btn-image i btn-title otrzymujemy widoki, które chcieliśmy uzyskać: wyzwalacze modali i otwarte okno.


Najczęstsze problemy
- Kliknięcie wyzwalacza nic nie robi. Sprawdź, czy motyw ładuje JavaScript Bootstrapa (i jQuery w wersji 4) oraz czy wersja Bootstrapa pasuje do atrybutów w kodzie (
data-togglew wersji 4,data-bs-togglew wersji 5). - Obraz wyzwalacza się nie wyświetla. Sprawdź, czy w parametrach widgetu wybrano obraz oraz czy blok
.btn-imagema w stylach motywu wysokość i szerokość.
Podsumowanie
Widget WPBakery z oknem modal wymaga dodania Bootstrapa do motywu WordPress. To nie jedyne rozwiązanie. Okno modal można też napisać samodzielnie, tylko w JavaScript i CSS, bez frameworka. My skorzystaliśmy z gotowych komponentów Bootstrapa, bo motyw już go zawierał, co ograniczyło nakład pracy. Kod zabezpiecza dane wyjściowe funkcjami esc_*, generuje niepowtarzalne ID funkcją wp_unique_id() i ładuje ikonę zamknięcia z folderu wtyczki.