charitable / includes / public / class-charitable-template.php

class-charitable-template.php in Charitable – Donation & Fundraising Platform (Donation Forms, Recurring Donations & Fundraising Campaigns) 1.8.12.2, at includes/public/class-charitable-template.php

264 lines 5.8 KB

Raw Download Zip

1	<?php
2	/**
3	* Charitable template.
4	*
5	* @package Charitable/Classes/Charitable_Template
6	* @author David Bisset
7	* @copyright Copyright (c) 2023, WP Charitable LLC
8	* @license http://opensource.org/licenses/gpl-2.0.php GNU Public License
9	* @since 1.0.0
10	* @version 1.0.0
11	*/
12
13	// Exit if accessed directly.
14	if ( ! defined( 'ABSPATH' ) ) {
15	exit;
16	}
17
18	if ( ! class_exists( 'Charitable_Template' ) ) :
19
20	/**
21	* Charitable_Template
22	*
23	* @since 1.0.0
24	*/
25	class Charitable_Template {
26
27	/**
28	* Theme template path.
29	*
30	* @since 1.0.0
31	*
32	* @var string
33	*/
34	protected $theme_template_path;
35
36	/**
37	* Base template path.
38	*
39	* @since 1.0.0
40	*
41	* @var string
42	*/
43	protected $base_template_path;
44
45	/**
46	* Template names to be loaded.
47	*
48	* @since 1.0.0
49	*
50	* @var string[]
51	*/
52	protected $template_names;
53
54	/**
55	* Whether to load template file if it is found.
56	*
57	* @since 1.0.0
58	*
59	* @var boolean
60	*/
61	protected $load;
62
63	/**
64	* Whether to use require_once or require.
65	*
66	* @since 1.0.0
67	*
68	* @var boolean
69	*/
70	protected $require_once;
71
72	/**
73	* The arguments available in the view.
74	*
75	* @since 1.0.0
76	*
77	* @var array
78	*/
79	protected $view_args;
80
81	/**
82	* Class constructor.
83	*
84	* @since 1.0.0
85	*
86	* @param string\|array $template_name A single template name or an ordered array of template.
87	* @param boolean $load If true the template file will be loaded if it is found.
88	* @param boolean $require_once Whether to require_once or require. Default true. Has no effect if $load is false.
89	*/
90	public function __construct( $template_name, $load = true, $require_once = true ) {
91	$this->load = $load;
92	$this->theme_template_path = $this->get_theme_template_path();
93	$this->base_template_path = $this->get_base_template_path();
94
95	/**
96	* Filter the template name.
97	*
98	* @since 1.0.0
99	*
100	* @param array $template_names Set of template names to check for.
101	*/
102	$this->template_names = apply_filters( 'charitable_template_name', (array) $template_name );
103	$this->view_args = array();
104
105	if ( $this->load ) {
106	$this->render( $require_once );
107	}
108	}
109
110	/**
111	* Set theme template path.
112	*
113	* @since 1.0.0
114	*
115	* @return string
116	*/
117	public function get_theme_template_path() {
118	/**
119	* Customize the directory to use for template files in themes/child themes.
120	*
121	* @since 1.0.0
122	*
123	* @param string $directory The directory, relative to the theme or child theme's root directory.
124	*/
125	return trailingslashit( apply_filters( 'charitable_theme_template_path', 'charitable' ) );
126	}
127
128	/**
129	* Return the base template path.
130	*
131	* @since 1.0.0
132	*
133	* @return string
134	*/
135	public function get_base_template_path() {
136	return charitable()->get_path( 'templates' );
137	}
138
139	/**
140	* Adds an array of view arguments.
141	*
142	* @since 1.0.0
143	*
144	* @param array $args Arguments to include in the view.
145	* @return void
146	*/
147	public function set_view_args( $args ) {
148	$this->view_args = array_merge( $this->view_args, $args );
149	}
150
151	/**
152	* Adds an argument to be accessed within the view.
153	*
154	* @since 1.0.0
155	*
156	* @param string $key The key of the argument.
157	* @param mixed $value The vaalue of the argument.
158	* @return void
159	*/
160	public function set_view_arg( $key, $value ) {
161	$this->view_args[ $key ] = $value;
162	}
163
164	/**
165	* Renders the template.
166	*
167	* @since 1.0.0
168	*
169	* @param boolean $require_once Whether the template should be loaded with include_once instead of include.
170	* @return false\|string False if the template does not exist. Template file otherwise.
171	*/
172	public function render( $require_once = true ) {
173	/* Make sure that the template file exists. */
174	$template = $this->locate_template();
175
176	if ( ! $this->template_file_exists( $template ) ) {
177	charitable_get_deprecated()->doing_it_wrong(
178	__FUNCTION__,
179	sprintf( '<code>%s</code> does not exist.', $template ),
180	'1.0.0'
181	);
182	return false;
183	}
184
185	if ( $template ) {
186
187	$view_args = $this->view_args;
188
189	if ( $this->require_once ) {
190	include_once( $template );
191	} else {
192	include( $template );
193	}
194	}
195
196	return $template;
197	}
198
199	/**
200	* Locate the template file of the highest priority.
201	*
202	* @uses locate_template()
203	*
204	* @since 1.0.0
205	*
206	* @return string
207	*/
208	public function locate_template() {
209	/* Template options are first checked in the theme/child theme using locate_template. */
210	$template = locate_template( $this->get_theme_template_options(), false );
211
212	/* No templates found in the theme/child theme, so use the plugin's default template. */
213	if ( ! $template ) {
214	$template = $this->base_template_path . $this->template_names[0];
215	}
216
217	/**
218	* Filter the template path before rendering it.
219	*
220	* @since 1.0.0
221	*
222	* @param string $template_path The template path to render.
223	* @param array $template_names Set of template names to check for.
224	*/
225	return apply_filters( 'charitable_locate_template', $template, $this->template_names );
226	}
227
228	/**
229	* Checks whether the template file exists.
230	*
231	* @since 1.0.0
232	*
233	* @param string $template The template file to check for.
234	* @return boolean
235	*/
236	public function template_file_exists( $template = '' ) {
237	if ( empty( $template ) ) {
238	$template = $this->locate_template();
239	}
240
241	return file_exists( $template );
242	}
243
244	/**
245	* Return the theme template options for a specific template.
246	*
247	* @since 1.0.0
248	*
249	* @return string[]
250	*/
251	protected function get_theme_template_options() {
252	$options = array();
253
254	foreach ( $this->template_names as $template_name ) {
255	$options[] = $this->theme_template_path . $template_name;
256	$options[] = $template_name;
257	}
258
259	return $options;
260	}
261	}
262
263	endif;
264