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

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

184 lines 9.1 KB

Raw Download Zip

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