suredonation / inc / page-builders / elementor / base-widget.php

base-widget.php in SureDonation – Donation Forms, Fundraising Campaigns & Donor Management 1.2.0, at inc/page-builders/elementor/base-widget.php

217 lines 6.0 KB

Raw Download Zip

1	<?php
2	/**
3	* Base Elementor widget.
4	*
5	* Shared plumbing for SureDonation's Elementor widgets: the widget category, the
6	* campaign selector control, and a render() that emits the matching SureDonation
7	* block's server-side output (so the widget stays 1:1 with Gutenberg).
8	*
9	* @package SureDonation
10	* @since 1.2.0
11	*/
12
13	namespace SureDonation\Inc\Page_Builders\Elementor;
14
15	use Elementor\Controls_Manager;
16	use Elementor\Plugin;
17	use Elementor\Widget_Base;
18	use SureDonation\Inc\Campaigns\Campaign_Page;
19	use SureDonation\Inc\Helper;
20	use SureDonation\Inc\Page_Builders\Page_Builders;
21
22	if ( ! defined( 'ABSPATH' ) ) {
23	exit; // Exit if accessed directly.
24	}
25
26	/**
27	* Base_Widget class.
28	*
29	* @since 1.2.0
30	*/
31	abstract class Base_Widget extends Widget_Base {
32
33	/**
34	* Widget category — every SureDonation widget lives under one category.
35	*
36	* @since 1.2.0
37	* @return array<int, string>
38	*/
39	public function get_categories() {
40	return [ Service_Provider::CATEGORY ];
41	}
42
43	/**
44	* Default keywords; subclasses may extend.
45	*
46	* @since 1.2.0
47	* @return array<int, string>
48	*/
49	public function get_keywords() {
50	return [ 'suredonation', 'donation', 'campaign' ];
51	}
52
53	/**
54	* Declare the campaign block styles as a widget dependency so Elementor
55	* enqueues them in the head whenever the widget is present. The block
56	* render's own wp_enqueue_style() would only run during the_content
57	* (footer print → FOUC); it remains as the non-Elementor fallback.
58	*
59	* @since 1.2.0
60	* @return array<int, string>
61	*/
62	public function get_style_depends() {
63	return [ 'suredonation-campaign-blocks' ];
64	}
65	/**
66	* The SureDonation block this widget renders (e.g. `suredonation/campaign-stats`).
67	*
68	* @since 1.2.0
69	* @return string
70	*/
71	abstract protected function block_name();
72
73	/**
74	* Map the widget settings to the block's attributes (camelCase, matching
75	* the block's Gutenberg attributes).
76	*
77	* @since 1.2.0
78	* @param array<string, mixed> $settings Widget settings.
79	* @return array<string, mixed>
80	*/
81	abstract protected function get_block_attrs( $settings );
82
83	/**
84	* Add the shared "Campaign" selector control (published campaigns).
85	*
86	* @since 1.2.0
87	* @return void
88	*/
89	protected function add_campaign_control() {
90	$this->add_control(
91	'campaign_id',
92	[
93	'label' => esc_html__( 'Campaign', 'suredonation' ),
94	'type' => Controls_Manager::SELECT2,
95	'label_block' => true,
96	'options' => Page_Builders::get_campaign_options(),
97	'default' => '',
98	'description' => esc_html__( 'Leave empty to use the current campaign when placed on a campaign page.', 'suredonation' ),
99	]
100	);
101	}
102
103	/**
104	* Render the widget by emitting the matching block's server-side output.
105	*
106	* @since 1.2.0
107	* @return void
108	*/
109	protected function render() {
110	$settings = $this->get_settings_for_display();
111	$campaign_id = $this->setting_int( $settings, 'campaign_id' );
112	$resolved = Campaign_Page::resolve_campaign_id( [ 'campaignId' => $campaign_id ] );
113
114	if ( ! $resolved ) {
115	if ( $this->is_edit_mode() ) {
116	$this->render_placeholder( esc_html__( 'Select a campaign to preview this widget.', 'suredonation' ) );
117	}
118	return;
119	}
120
121	$attrs = $this->get_block_attrs( $settings );
122	$attrs['campaignId'] = $resolved;
123
124	$this->echo_block( $attrs );
125	}
126
127	/**
128	* Emit the widget's block with the given attributes. render_block() runs the
129	* block's registered render_callback, producing the exact same
130	* (already-escaped) markup as the Gutenberg block.
131	*
132	* @since 1.2.0
133	* @param array<string, mixed> $attrs Block attributes.
134	* @return void
135	*/
136	protected function echo_block( array $attrs ) {
137	echo render_block( // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- Block render output is escaped in the block's render callback.
138	[
139	'blockName' => $this->block_name(),
140	'attrs' => $attrs,
141	'innerBlocks' => [],
142	'innerHTML' => '',
143	'innerContent' => [],
144	]
145	);
146	}
147
148	/**
149	* Whether Elementor is in edit mode.
150	*
151	* @since 1.2.0
152	* @return bool
153	*/
154	protected function is_edit_mode() {
155	return class_exists( '\Elementor\Plugin' ) && Plugin::instance()->editor->is_edit_mode();
156	}
157
158	/**
159	* Print an editor-only placeholder message.
160	*
161	* @since 1.2.0
162	* @param string $message Placeholder text.
163	* @return void
164	*/
165	protected function render_placeholder( $message ) {
166	printf(
167	'<div class="suredonation-elementor-placeholder" style="padding:20px;text-align:center;border:1px dashed #c3c4c7;border-radius:6px;color:#50575e;">%s</div>',
168	esc_html( $message )
169	);
170	}
171
172	/**
173	* Read a setting as a string (settings values are mixed).
174	*
175	* @since 1.2.0
176	* @param array<string, mixed> $settings Widget settings.
177	* @param string $key Setting key.
178	* @param string $fallback Fallback when empty/unset.
179	* @return string
180	*/
181	protected function setting_string( $settings, $key, $fallback = '' ) {
182	if ( ! isset( $settings[ $key ] ) \|\| '' === $settings[ $key ] ) {
183	return $fallback;
184	}
185	return Helper::get_string_value( $settings[ $key ] );
186	}
187
188	/**
189	* Read a setting as a non-negative integer.
190	*
191	* @since 1.2.0
192	* @param array<string, mixed> $settings Widget settings.
193	* @param string $key Setting key.
194	* @param int $fallback Fallback when unset.
195	* @return int
196	*/
197	protected function setting_int( $settings, $key, $fallback = 0 ) {
198	return isset( $settings[ $key ] ) ? absint( Helper::get_string_value( $settings[ $key ] ) ) : $fallback;
199	}
200
201	/**
202	* Read an Elementor SWITCHER setting as a boolean ('yes' === on).
203	*
204	* @since 1.2.0
205	* @param array<string, mixed> $settings Widget settings.
206	* @param string $key Setting key.
207	* @param bool $fallback Fallback when unset.
208	* @return bool
209	*/
210	protected function setting_bool( $settings, $key, $fallback = false ) {
211	if ( ! isset( $settings[ $key ] ) ) {
212	return $fallback;
213	}
214	return 'yes' === Helper::get_string_value( $settings[ $key ] );
215	}
216	}
217