charitable / includes / fields / class-charitable-campaign-field.php

class-charitable-campaign-field.php in Charitable – Donation & Fundraising Platform (Donation Forms, Recurring Donations & Fundraising Campaigns) 1.7.0.14, at includes/fields/class-charitable-campaign-field.php

207 lines 9.5 KB

Raw Download Zip

1	<?php
2	/**
3	* Charitable_Campaign_Field model.
4	*
5	* @package Charitable/Classes/Charitable_Campaign_Field
6	* @author David Bisset
7	* @copyright Copyright (c) 2022, WP Charitable LLC
8	* @license http://opensource.org/licenses/gpl-2.0.php GNU Public License
9	* @since 1.6.0
10	* @version 1.6.25
11	*/
12
13	// Exit if accessed directly.
14	if ( ! defined( 'ABSPATH' ) ) {
15	exit;
16	}
17
18	if ( ! class_exists( 'Charitable_Campaign_Field' ) ) :
19
20	/**
21	* Charitable_Campaign_Field
22	*
23	* @since 1.6.0
24	*
25	* @property string $field
26	* @property string $label
27	* @property string $data_type
28	* @property false\|callable $value_callback
29	* @property boolean\|array $admin_form
30	* @property boolean\|array $campaign_form
31	* @property boolean $show_in_export
32	* @property boolean\|array $email_tag
33	*/
34	class Charitable_Campaign_Field extends Charitable_Field implements Charitable_Field_Interface {
35
36	/**
37	* Field identifier.
38	*
39	* @since 1.6.0
40	*
41	* @var string
42	*/
43	protected $field;
44
45	/**
46	* Field arguments.
47	*
48	* @since 1.6.0
49	*
50	* @var array $args {
51	* Array of field arguments.
52	*
53	* @type string $label The label to use in the export, meta, Ambassadors campaign form (unless overridden),
54	* admin form (unless overriden) and email tag (unless overridden).
55	* If no `label` is provided in the campaign_form args, this label will be used in
56	* the Ambassadors campaign form. If no `label` is provided in the admin_form args, this
57	* label will also be used in the admin form. Unless a `description` is set in the
58	* `email_tag` args, this label will also be used there as the tag description.
59	* @type string $data_type How the data should be saved. This may be set to 'meta' or 'core', through 'core'
60	* is designed stricly for core Charitable use.
61	* @type false\|callable $value_callback A callback function to retrieve the value of the field for a campaign.
62	* The callback function receives up to two arguments: a `Charitable_Campaign` object
63	* and the field key.
64	* Note that this should only be set to false if either of the following is true:
65	* `Charitable_Campaign` has a getter named `get_$key` where `$key` is the field of
66	* this key; or $key is a member variable of `WP_Post`.
67	* @type boolean\|array $admin_form {
68	* Sets whether the field should be shown in the admin form. To prevent the field being available
69	* in the form (not even as a hidden input), set to false. For control over how the field should be
70	* shown in the form, an array can be passed with any of these keys:
71	*
72	* @type string $label The field label. This will override the `label` set above.
73	* @type string $type The type of field. Options include (but may not be limited to):
74	* text, email, password, date, datepicker, checkbox, multi-checkbox, select,
75	* radio, file, fieldset, editor (uses WP Editor), textarea, number, picture,
76	* url and hidden.
77	* This will default to text.
78	* @type boolean $required Whether this is a required field.
79	* @type array $options Provide a set of options. This is required when `type` is select, radio or
80	* multi-checkbox. These should be provided in a simple value=>label array,
81	* where the label is what people see when they select an option, and value
82	* is what gets stored in the database.
83	* @type mixed $default The default value for this field.
84	* @type boolean $fullwidth Whether to show the field as a full-width field.
85	* @type array $attrs Arbitrary set of form field attributes. These should be provided in a simple
86	* key=>value array, which will be parsed as key="value" attributes in the field.
87	* @type string $section The section or panel that the field should be included in.
88	* @type int $priority Set the position of the field within the form. This overrides `show_after`
89	* and `show_before`. If `priority`, `show_after` and `show_before` are not set,
90	* the field will be shown after the most recently registered form field.
91	* @type string $show_after Specify another field that this field should be shown after.
92	* If `priority` is set, this field is ignored. Note that if multiple fields
93	* are set to show after the same field, it may not appear immediately after the
94	* other field. Use in combination with `show_before` or use `priority` instead
95	* for fine-grained control.
96	* @type string $show_before Specify another field that this field should be shown before.
97	* If `priority` is set, this field is ignored. Note that if multiple fields
98	* are set to show before the same field, it may not appear immediately before
99	* the other field. Use in combination with `show_after` or use `priority`
100	* instead for fine-grained control.
101	* @type false\|callable $value_callback A callback function to retrieve the value of the field for a campaign.
102	* This will override the `value_callback` setting for the field.
103	* }
104	* @type boolean\|array $campaign_form {
105	* Sets whether the field should be shown in the Ambassadors campaign form. To prevent the field being available
106	* in the form (not even as a hidden input), set to false. If set to true, the form field will inherit arguments
107	* from the `admin_form` (if provided), or use default arguments. For control over how the field should be
108	* shown in the form, an array can be passed with the same keys as described for `admin_form` above.
109	* }
110	* @type boolean $show_in_export Whether the field should be shown in campaign exports.
111	* @type boolean\|array $email_tag {
112	* Automatically create an email tag for this field. Set to false to prevent the field being available as an
113	* email tag. For control over the email tag options, an array can be passed with the following keys:
114	*
115	* @type string $description The description shown for the email tag. If no description is set, the `label`
116	* will be used.
117	* @type string $tag The email tag. If this is not provided, the field key will be used.
118	* @type string $preview A value to use in email previews for this field.
119	* }
120	* }
121	*/
122	protected $args;
123
124	/**
125	* Return the default arguments for this field type.
126	*
127	* @since 1.6.0
128	*
129	* @return array
130	*/
131	protected function get_defaults() {
132	return array(
133	'label' => '',
134	'data_type' => 'meta',
135	'value_callback' => false,
136	'campaign_form' => true,
137	'admin_form' => true,
138	'show_in_export' => true,
139	'email_tag' => true,
140	);
141	}
142
143	/**
144	* Sanitize the argument.
145	*
146	* @since 1.6.0
147	*
148	* @param string $key The argument's key.
149	* @param mixed $value The argument's value.
150	* @return mixed The argument value after being registered.
151	*/
152	protected function sanitize_arg( $key, $value ) {
153	$value = parent::sanitize_arg( $key, $value );
154
155	if ( in_array( $key, array( 'show_in_export' ) ) ) {
156	return (bool) $value;
157	}
158
159	return $value;
160	}
161
162	/**
163	* Sanitize the campaign_form setting.
164	*
165	* @since 1.6.0
166	*
167	* @param mixed $value The argument setting.
168	* @return boolean\|array
169	*/
170	protected function sanitize_campaign_form( $value ) {
171	return $this->sanitize_form_arg(
172	$value,
173	array(
174	'type' => 'text',
175	'required' => false,
176	'fullwidth' => false,
177	'default' => '',
178	'attrs' => array(),
179	)
180	);
181	}
182
183	/**
184	* Sanitize the admin_form setting.
185	*
186	* @since 1.6.0
187	*
188	* @param mixed $value The argument setting.
189	* @return boolean\|array
190	*/
191	public function sanitize_admin_form( $value ) {
192	return $this->sanitize_form_arg(
193	$value,
194	array(
195	'type' => 'text',
196	'required' => false,
197	'fullwidth' => false,
198	'default' => '',
199	'attrs' => array(),
200	'section' => charitable()->campaign_fields()->get_default_section( 'admin' ),
201	)
202	);
203	}
204	}
205
206	endif;
207