1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
|
<?php
/**
* The base class for all SiteOrigin_Widget form fields.
*
* Class SiteOrigin_Widget_Field
*/
abstract class SiteOrigin_Widget_Field_Base {
/* ============================================================================================================== */
/* CORE FIELD PROPERTIES */
/* Properties which are essential to successful rendering of fields and saving of data input into fields. */
/* ============================================================================================================== */
/**
* The base name for this field. It is used in the generation of HTML element id and name attributes.
*
* @access protected
* @var string
*/
protected $base_name;
/**
* The rendered HTML element id attribute.
*
* @access protected
* @var string
*/
protected $element_id;
/**
* The rendered HTML element name attribute
*
* @access protected
* @var string
*/
protected $element_name;
/**
* The field configuration options.
*
* @access protected
* @var array
*/
protected $field_options;
/**
* Variables may be added to this array which will be propagated to the front end for use in dynamic rendering.
*
* @access protected
* @var array
*/
protected $javascript_variables;
/* ============================================================================================================== */
/* BASE FIELD CONFIGURATION PROPERTIES */
/* Common configuration properties used by all fields. */
/* ============================================================================================================== */
/**
* The type of the field.
*
* @access protected
* @var string
*/
protected $type;
/**
* Render a label for the field with the given value.
*
* @access protected
* @var string
*/
protected $label;
/**
* The field will be prepopulated with this default value.
*
* @access protected
* @var mixed
*/
protected $default;
/**
* Render small italic text below the field to describe the field's purpose.
*
* @access protected
* @var string
*/
protected $description;
/**
* Append '(Optional)' to this field's label as a small green superscript.
*
* @access protected
* @var bool
*/
protected $optional;
/**
* @var bool Is this field required.
*/
protected $required;
/**
* Specifies an additional sanitization to be performed. Available sanitizations are 'email' and 'url'. If the
* specified sanitization isn't recognized it is assumed to be a custom sanitization and a filter is applied using
* the pattern `'siteorigin_widgets_sanitize_field_' . $sanitize`, in case the sanitization is defined elsewhere.
*
* @access protected
* @var string
*/
protected $sanitize;
/**
* Reference to the parent widget required for creating child fields.
*
* @access private
* @var SiteOrigin_Widget
*/
protected $for_widget;
/**
* An array of field names of parent containers.
*
* @var array
*/
protected $parent_container;
/**
* Whether or not this field contains other fields.
*
* @access protected
* @var boolean
*/
protected $is_container;
/**
* Additional CSS classes to output in this field's HTML class attribute. It is left up to the field's render_field
* function to output these classes.
*
* @access protected
* @var array
*/
protected $input_css_classes;
/* ============================================================================================================== */
/* FIELD STATES PROPERTIES */
/* Configuration of field state emitters and handlers. */
/* See https://siteorigin.com/docs/widgets-bundle/form-building/state-emitters/ for more detail on the topic of */
/* state emitters and handlers. */
/* ============================================================================================================== */
/**
*
* Specifies the callback type and arguments to use when deciding on the state to be emitted.
*
* @access protected
* @var array
*/
protected $state_emitter;
/**
*
* Specifies the different possible states to be handled by this field and the resulting effect of the each state.
*
* @access protected
* @var array
*/
protected $state_handler;
/**
* @var
*/
protected $state_handler_initial;
/**
* @param $base_name string The name of the field.
* @param $element_id string The id to be used as the id attribute of the wrapping HTML element.
* @param $element_name string The name to be used as the name attribute of the wrapping HTML element.
* @param $field_options array Configuration for the field.
*
* @param SiteOrigin_Widget $for_widget
* @param array $parent_container
*
* @throws InvalidArgumentException
*/
public function __construct( $base_name, $element_id, $element_name, $field_options, $for_widget = null, $parent_container = array() ) {
if( isset( $field_options['type'] ) ) {
$this->type = $field_options['type'];
}
else {
throw new InvalidArgumentException( 'SiteOrigin_Widget_Field_Base::__construct: $field_options must contain a \'type\' field.' );
}
$this->base_name = $base_name;
$this->element_id = $element_id;
$this->element_name = $element_name;
$this->field_options = $field_options;
$this->javascript_variables = array();
$this->for_widget = $for_widget;
$this->parent_container = $parent_container;
$this->init();
}
private function init() {
$this->init_options();
$this->initialize();
}
/**
* Initialization function which may be overridden if required.
*/
protected function initialize() {
}
/**
* This method ensures that configuration options are set on the corresponding field class instance properties. If
* a field has defined default options, those are set first and then can be overwritten by options which were
* passed in.
*/
private function init_options() {
// First set properties from default options if any have been set.
$default_field_options = $this->get_default_options();
if( ! empty( $default_field_options ) ) {
foreach ( $default_field_options as $key => $value ) {
if ( property_exists( $this, $key ) ) {
if ( isset( $default_field_options[$key] ) ) {
$this->$key = $value;
}
}
}
}
$field_options = $this->field_options;
foreach ( $field_options as $key => $value ) {
if( property_exists( $this, $key ) ) {
if ( isset( $field_options[$key] ) ) {
$this->$key = $value;
}
}
}
}
protected function get_default_options() {
//Stub: This function may be overridden by subclasses to have default field options.
return null;
}
/**
* The CSS classes to be applied to the default label.
* This function should be overridden by subclasses when they want to add custom CSS classes to the HTML input label.
*
* @return array The array of label CSS classes.
*/
protected function get_label_classes( $value, $instance ) {
return array( 'siteorigin-widget-field-label' );
}
/**
* The CSS classes to be applied to the default description.
* This function should be overridden by subclasses when they want to add custom CSS classes to the description text.
*
* @return array The modified array of description text CSS classes.
*/
protected function get_description_classes() {
return array( 'siteorigin-widget-description' );
}
/**
* This function is called by the containing SiteOrigin_Widget when rendering it's form.
*
* @param $value mixed The current instance value of the field.
* @param $instance array Optionally pass in the widget instance, if rendering of additional values is required.
*/
public function render( $value, $instance = array() ) {
if ( is_null( $value ) && isset( $this->default ) ) {
$value = $this->default;
}
$wrapper_attributes = array(
'class' => array(
'siteorigin-widget-field',
'siteorigin-widget-field-type-' . $this->type,
'siteorigin-widget-field-' . $this->base_name
)
);
if( !empty( $this->optional ) ) $wrapper_attributes['class'][] = 'siteorigin-widget-field-is-optional';
if( !empty( $this->required ) ) $wrapper_attributes['class'][] = 'siteorigin-widget-field-is-required';
$wrapper_attributes['class'] = implode(' ', array_map('sanitize_html_class', $wrapper_attributes['class']) );
if( !empty( $this->state_emitter ) ) {
// State emitters create new states for the form
$wrapper_attributes['data-state-emitter'] = json_encode( $this->state_emitter );
}
if( !empty( $this->state_handler ) ) {
// State handlers decide what to do with form states
$wrapper_attributes['data-state-handler'] = json_encode( $this->state_handler );
}
if( !empty( $this->state_handler_initial ) ) {
// Initial state handlers are only run when the form is first loaded
$wrapper_attributes['data-state-handler-initial'] = json_encode( $this->state_handler_initial );
}
?><div <?php foreach( $wrapper_attributes as $attr => $attr_val ) echo $attr.'="' . esc_attr( $attr_val ) . '" ' ?>><?php
// Allow subclasses and to render something before and after the render_field() function is called.
$this->render_before_field( $value, $instance );
$this->render_field( $value, array() );
$this->render_after_field( $value, $instance);
?></div><?php
}
/**
* This function is called before the main render function.
*
* @param $value mixed The current value of this field.
* @param $instance array The current widget instance.
*/
protected function render_before_field( $value, $instance ) {
$this->render_field_label( $value, $instance );
}
/**
* Default label rendering implementation. Subclasses should override if necessary to render labels differently.
*/
protected function render_field_label( $value, $instance ) {
?>
<label for="<?php echo esc_attr( $this->element_id ) ?>" <?php $this->render_CSS_classes( $this->get_label_classes( $value, $instance ) ) ?>>
<?php
echo esc_html( $this->label );
if( !empty( $this->optional ) ) {
echo '<span class="field-optional">(' . __('Optional', 'so-widgets-bundle') . ')</span>';
}
if( !empty( $this->required ) ) {
echo '<span class="field-required">(' . __('Required', 'so-widgets-bundle') . ')</span>';
}
?>
</label>
<?php
}
/**
* Helper function to render the HTML class attribute with the array of classes.
*/
protected function render_CSS_classes( $CSS_classes ) {
if( ! empty( $CSS_classes ) ) {
?>class="<?php echo esc_attr( implode( ' ', array_map( 'sanitize_html_class', $CSS_classes ) ) ) ?>"<?php
}
}
/**
*
* The main field rendering function. This function should be overridden by all subclasses and used to render their
* specific form field HTML for display.
*
* @param $value mixed The current value of this field.
* @param $instance array The current widget instance.
* @return mixed Should output the desired HTML.
*/
abstract protected function render_field( $value, $instance );
/**
* The default sanitization function.
*
* @param $value mixed The value to be sanitized.
* @param $instance array The widget instance.
* @param $old_value mixed The old value of this field.
*
* @return mixed|string
*/
public function sanitize( $value, $instance = array(), $old_value = null ) {
$value = $this->sanitize_field_input( $value, $instance );
if( isset( $this->sanitize ) ) {
// This field also needs some custom sanitization
switch( $this->sanitize ) {
case 'url':
$value = sow_esc_url_raw( $value );
break;
case 'email':
$value = sanitize_email( $value );
break;
default:
// This isn't a built in sanitization. Maybe it's handled elsewhere.
if( is_callable( $this->sanitize ) ) {
$value = call_user_func( $this->sanitize, $value, $old_value );
}
else if( is_string( $this->sanitize ) ) {
$value = apply_filters( 'siteorigin_widgets_sanitize_field_' . $this->sanitize, $value );
}
break;
}
}
return $value;
}
/**
* This function is called after the main render function.
*
* @param $value mixed The current value of this field.
* @param $instance array The current widget instance.
*/
protected function render_after_field( $value, $instance ) {
$this->render_field_description();
}
/**
* Default description rendering implementation. Subclasses should override if necessary to render descriptions
* differently.
*/
protected function render_field_description() {
if( ! empty( $this->description ) ) {
?><div <?php $this->render_CSS_classes( $this->get_description_classes() ) ?>><?php echo wp_kses_post( $this->description ) ?></div><?php
}
}
/**
*
* The main sanitization function. This function should be overridden by all subclasses and used to sanitize the
* input received from their HTML form field.
*
* @param $value mixed The current value of this field.
* @param $instance array The widget instance.
*
* @return mixed The sanitized value.
*/
abstract protected function sanitize_field_input( $value, $instance );
/**
* There are cases where a field may affect values on the widget instance, other than it's own input. It then becomes
* necessary to perform additional sanitization on the widget instance, which should be done here.
*
* @param $instance
* @return mixed
*/
public function sanitize_instance( $instance ) {
//Stub: This function may be overridden by subclasses wishing to sanitize additional instance fields.
return $instance;
}
/**
* Occasionally it is necessary for a field to set a variable to be used in the front end. Override this function
* and set any necessary values on the `javascript_variables` instance property.
*
* @return array
*/
public function get_javascript_variables() {
return $this->javascript_variables;
}
/**
* Some more complex fields may require some JavaScript in the front end. Enqueue them here.
*/
public function enqueue_scripts() {
}
public function __get( $name ) {
if ( isset( $this->$name ) ) {
return $this->$name;
}
}
}
|