wp-parsely / src / UI / class-recommended-widget.php

class-recommended-widget.php in Parse.ly 3.20.2, at src/UI/class-recommended-widget.php

329 lines 13.8 KB

Raw Download Zip

1	<?php
2	/**
3	* UI: Recommended Widget class
4	*
5	* Provides a widget with Parse.ly recommended articles.
6	*
7	* @package Parsely
8	*/
9
10	declare(strict_types=1);
11
12	namespace Parsely\UI;
13
14	use Parsely\Parsely;
15	use Parsely\Utils\Utils;
16	use WP_Widget;
17
18	use const Parsely\PARSELY_FILE;
19
20	/**
21	* Provides a widget with Parse.ly recommended articles.
22	*
23	* @phpstan-type Widget_Settings array{
24	* title: string,
25	* return_limit: int,
26	* display_direction: string,
27	* published_within: int,
28	* sort: string,
29	* personalize_results: bool,
30	* img_src: string,
31	* display_author: bool,
32	* }
33	*/
34	final class Recommended_Widget extends WP_Widget {
35	/**
36	* Instance of Parsely class.
37	*
38	* @var Parsely
39	*/
40	private $parsely;
41
42	/**
43	* Default values of widget settings
44	*
45	* @var Widget_Settings
46	*/
47	private static $default_widget_settings = array(
48	'title' => '',
49	'return_limit' => 5,
50	'display_direction' => 'vertical',
51	'published_within' => 0,
52	'sort' => 'score',
53	'personalize_results' => false,
54	'img_src' => 'parsely_thumb',
55	'display_author' => false,
56	);
57
58	/**
59	* Constructor.
60	*
61	* @param Parsely $parsely Instance of Parsely class.
62	*/
63	public function __construct( Parsely $parsely ) {
64	parent::__construct(
65	'Parsely_Recommended_Widget',
66	__( 'Parse.ly Recommended Widget', 'wp-parsely' ),
67	array(
68	'classname' => 'Recommended_Widget parsely-recommended-widget-hidden',
69	'description' => __( 'Display a list of post recommendations, personalized for a visitor or the current post.', 'wp-parsely' ),
70	)
71	);
72
73	$this->parsely = $parsely;
74	}
75
76	/**
77	* Gets the URL for the Recommendations API (GET /related).
78	*
79	* @since 2.5.0
80	*
81	* @see https://docs.parse.ly/content-recommendations/
82	*
83	* @internal While this is a public method now, this should be moved to a new class.
84	*
85	* @param string $site_id Publisher Site ID.
86	* @param int\|null $published_within Publication filter start date; see https://docs.parse.ly/api-date-time/ for
87	* formatting details. No restriction by default.
88	* @param string\|null $sort What to sort the results by. There are currently 2 valid options: `score`,
89	* which will sort articles by overall relevance and `pub_date` which will sort
90	* results by their publication date. The default is `score`.
91	* @param int $return_limit Number of records to retrieve; defaults to "10".
92	* @return string API URL.
93	*/
94	private function get_api_url( string $site_id, ?int $published_within, ?string $sort, int $return_limit ): string {
95	$related_api_endpoint = $this->parsely->get_content_api()->get_endpoint( '/related' );
96
97	$query_args = array(
98	'apikey' => $site_id,
99	'sort' => $sort,
100	'limit' => $return_limit,
101	);
102
103	if ( null !== $published_within && 0 !== $published_within ) {
104	$query_args['pub_date_start'] = $published_within . 'd';
105	}
106
107	return $related_api_endpoint->get_endpoint_url( $query_args );
108	}
109
110	/**
111	* This is the widget function.
112	*
113	* @param array<string, string> $args Widget Arguments.
114	* @param array<mixed> $widget_settings Values saved to the db.
115	*/
116	public function widget( $args, $widget_settings ): void /* @phpstan-ignore-line */ {
117	if ( ! $this->site_id_and_secret_are_populated() ) {
118	return;
119	}
120
121	$instance = $this->get_widget_settings( $widget_settings );
122	$removed_title_esc = remove_filter( 'widget_title', 'esc_html' );
123
124	/** This filter is documented in wp-includes/widgets/class-wp-widget-pages.php */
125	$title = apply_filters( 'widget_title', $instance['title'] );
126
127	if ( $removed_title_esc ) {
128	add_filter( 'widget_title', 'esc_html' );
129	}
130
131	$title_html = $args['before_widget'] . $args['before_title'] . $title . $args['after_title'];
132	echo wp_kses_post( $title_html );
133
134	// Set up the variables.
135	$api_url = $this->get_api_url(
136	$this->parsely->get_site_id(),
137	(int) $instance['published_within'], // @phpstan-ignore-line
138	$instance['sort'],
139	(int) $instance['return_limit'] // @phpstan-ignore-line
140	);
141
142	?>
143
144	<div class="parsely-recommended-widget"
145	data-parsely-widget-display-author="<?php echo esc_attr( (string) wp_json_encode( $instance['display_author'] ) ); ?>"
146	data-parsely-widget-display-direction="<?php echo esc_attr( $instance['display_direction'] ); ?>"
147	data-parsely-widget-api-url="<?php echo esc_url( $api_url ); ?>"
148	data-parsely-widget-img-display="<?php echo esc_attr( $instance['img_src'] ); ?>"
149	data-parsely-widget-permalink="<?php echo esc_url( (string) get_permalink() ); ?>"
150	data-parsely-widget-personalized="<?php echo esc_attr( (string) wp_json_encode( $instance['personalize_results'] ) ); ?>"
151	data-parsely-widget-id="<?php echo esc_attr( (string) $this->id ); ?>"
152	></div>
153
154	<?php
155
156	$recommended_widget_script_asset = Utils::get_asset_info( 'build/recommended-widget.asset.php' );
157
158	wp_register_script(
159	'wp-parsely-recommended-widget',
160	plugin_dir_url( PARSELY_FILE ) . 'build/recommended-widget.js',
161	$recommended_widget_script_asset['dependencies'],
162	$recommended_widget_script_asset['version'],
163	true
164	);
165
166	wp_register_style(
167	'wp-parsely-recommended-widget',
168	plugin_dir_url( PARSELY_FILE ) . 'build/recommended-widget.css',
169	array(),
170	$recommended_widget_script_asset['version']
171	);
172
173	wp_enqueue_script( 'wp-parsely-recommended-widget' );
174	wp_enqueue_style( 'wp-parsely-recommended-widget' );
175
176	echo wp_kses_post( $args['after_widget'] );
177	}
178
179	/**
180	* This is the form function.
181	*
182	* @param array<mixed> $current_settings Values saved to the db.
183	*/
184	public function form( $current_settings ): string {
185	if ( ! $this->site_id_and_secret_are_populated() ) {
186	$settings_page_url = add_query_arg( 'page', 'parsely-settings', get_admin_url() . 'admin.php' );
187
188	$message = sprintf(
189	/* translators: %s: Plugin settings page URL */
190	__( 'The <i>Parse.ly Site ID</i> and <i>Parse.ly API Secret</i> fields need to be populated on the <a href="%s">Parse.ly settings page</a> for this widget to work.', 'wp-parsely' ),
191	esc_url( $settings_page_url )
192	);
193
194	echo '<p>', wp_kses_post( $message ), '</p>';
195
196	return '';
197	}
198
199	$instance = $this->get_widget_settings( $current_settings );
200
201	// editable fields: title.
202	$title = $instance['title'];
203	$return_limit = $instance['return_limit'];
204	$display_direction = $instance['display_direction'];
205	$published_within = $instance['published_within'];
206	$sort = $instance['sort'];
207	$personalize_results = $instance['personalize_results'];
208	$img_src = $instance['img_src'];
209	$display_author = $instance['display_author'];
210
211	$instance['return_limit'] = $return_limit;
212	$instance['display_direction'] = $display_direction;
213	$instance['published_within'] = $published_within;
214	$instance['sort'] = $sort;
215	$instance['personalize_results'] = $personalize_results;
216	$instance['img_src'] = $img_src;
217	$instance['display_author'] = $display_author;
218
219	?>
220	<p>
221	<label for="<?php echo esc_attr( $this->get_field_id( 'title' ) ); ?>"><?php esc_html_e( 'Title:', 'wp-parsely' ); ?></label>
222	<br>
223	<input type="text" id="<?php echo esc_attr( $this->get_field_id( 'title' ) ); ?>" name="<?php echo esc_attr( $this->get_field_name( 'title' ) ); ?>" value="<?php echo esc_attr( $title ); ?>" class="widefat" />
224	</p>
225	<p>
226	<label for="<?php echo esc_attr( $this->get_field_id( 'published_within' ) ); ?>" id="<?php echo esc_attr( $this->get_field_id( 'published_within_label' ) ); ?>"><?php esc_html_e( 'Published within', 'wp-parsely' ); ?></label>
227	<input type="number" id="<?php echo esc_attr( $this->get_field_id( 'published_within' ) ); ?>" name="<?php echo esc_attr( $this->get_field_name( 'published_within' ) ); ?>" value="<?php echo esc_attr( (string) $instance['published_within'] ); ?>" min="0" max="30"
228	class="tiny-text" aria-labelledby="<?php echo esc_attr( $this->get_field_id( 'published_within_label' ) ); ?> <?php echo esc_attr( $this->get_field_id( 'published_within' ) ); ?> <?php echo esc_attr( $this->get_field_id( 'published_within_unit' ) ); ?>" />
229	<span id="<?php echo esc_attr( $this->get_field_id( 'published_within_unit' ) ); ?>"> <?php esc_html_e( 'days (0 for no limit).', 'wp-parsely' ); ?></span>
230	</p>
231	<p>
232	<label for="<?php echo esc_attr( $this->get_field_id( 'return_limit' ) ); ?>"><?php esc_html_e( 'Number of posts to show (max 20):', 'wp-parsely' ); ?></label>
233	<input type="number" id="<?php echo esc_attr( $this->get_field_id( 'return_limit' ) ); ?>" name="<?php echo esc_attr( $this->get_field_name( 'return_limit' ) ); ?>" value="<?php echo esc_attr( (string) $instance['return_limit'] ); ?>" min="1" max="20" class="tiny-text" />
234	</p>
235	<p>
236	<fieldset>
237	<legend><?php esc_html_e( 'Display entries:', 'wp-parsely' ); ?></legend>
238	<p>
239	<input type="radio" id="<?php echo esc_attr( $this->get_field_id( 'display_direction_horizontal' ) ); ?>" name="<?php echo esc_attr( $this->get_field_name( 'display_direction' ) ); ?>"<?php checked( $instance['display_direction'], 'horizontal' ); ?> value="horizontal" />
240	<label for="<?php echo esc_attr( $this->get_field_id( 'display_direction_horizontal' ) ); ?>"><?php esc_html_e( 'Horizontally', 'wp-parsely' ); ?></label>
241	<br />
242	<input type="radio" id="<?php echo esc_attr( $this->get_field_id( 'display_direction_vertical' ) ); ?>" name="<?php echo esc_attr( $this->get_field_name( 'display_direction' ) ); ?>"<?php checked( $instance['display_direction'], 'vertical' ); ?> value="vertical" />
243	<label for="<?php echo esc_attr( $this->get_field_id( 'display_direction_vertical' ) ); ?>"><?php esc_html_e( 'Vertically', 'wp-parsely' ); ?></label>
244	</p>
245	</fieldset>
246	</p>
247	<p>
248	<label for="<?php echo esc_attr( $this->get_field_id( 'sort' ) ); ?>"><?php esc_html_e( 'Sort by:', 'wp-parsely' ); ?></label>
249	<br>
250	<select id="<?php echo esc_attr( $this->get_field_id( 'sort' ) ); ?>" name="<?php echo esc_attr( $this->get_field_name( 'sort' ) ); ?>" class="widefat">
251	<option<?php selected( $instance['sort'], 'score' ); ?> value="score"><?php esc_html_e( 'Score', 'wp-parsely' ); ?></option>
252	<option<?php selected( $instance['sort'], 'pub_date' ); ?> value="pub_date"><?php esc_html_e( 'Publish date', 'wp-parsely' ); ?></option>
253	</select>
254	</p>
255	<p>
256	<label for="<?php echo esc_attr( $this->get_field_id( 'img_src' ) ); ?>"><?php esc_html_e( 'Image source:', 'wp-parsely' ); ?></label>
257	<br>
258	<select id="<?php echo esc_attr( $this->get_field_id( 'img_src' ) ); ?>" name="<?php echo esc_attr( $this->get_field_name( 'img_src' ) ); ?>" class="widefat">
259	<option<?php selected( $instance['img_src'], 'parsely_thumb' ); ?> value="parsely_thumb"><?php esc_html_e( 'Parse.ly generated thumbnail (85x85px)', 'wp-parsely' ); ?></option>
260	<option<?php selected( $instance['img_src'], 'original' ); ?> value="original"><?php esc_html_e( 'Original image', 'wp-parsely' ); ?></option>
261	<option<?php selected( $instance['img_src'], 'none' ); ?> value="none"><?php esc_html_e( 'No image', 'wp-parsely' ); ?></option>
262	</select>
263	</p>
264	<p>
265	<input type="checkbox" id="<?php echo esc_attr( $this->get_field_id( 'display_author' ) ); ?>" name="<?php echo esc_attr( $this->get_field_name( 'display_author' ) ); ?>" value="display_author"<?php checked( $instance['display_author'], 'display_author' ); ?> />
266	<label for="<?php echo esc_attr( $this->get_field_id( 'display_author' ) ); ?>"><?php esc_html_e( 'Display author', 'wp-parsely' ); ?></label>
267	<br />
268	<input type="checkbox" id="<?php echo esc_attr( $this->get_field_id( 'personalize_results' ) ); ?>" name="<?php echo esc_attr( $this->get_field_name( 'personalize_results' ) ); ?>" value="personalize_results"<?php checked( $instance['personalize_results'], 'personalize_results' ); ?> />
269	<label for="<?php echo esc_attr( $this->get_field_id( 'personalize_results' ) ); ?>"><?php esc_html_e( 'Personalize recommended results', 'wp-parsely' ); ?></label>
270	</p>
271	<?php
272
273	return '';
274	}
275
276	/**
277	* This is the update function.
278	*
279	* @param Widget_Settings $new_instance The new values for the db.
280	* @param Widget_Settings $old_instance Values saved to the db.
281	* @return Widget_Settings
282	*/
283	public function update( $new_instance, $old_instance ) /* @phpstan-ignore-line */ {
284	$instance = $old_instance;
285	$instance['title'] = trim( wp_kses_post( $new_instance['title'] ) );
286	$instance['published_within'] = $new_instance['published_within'];
287	$instance['return_limit'] = $new_instance['return_limit'] <= 20 ? $new_instance['return_limit'] : 20;
288	$instance['display_direction'] = trim( $new_instance['display_direction'] );
289	$instance['sort'] = trim( $new_instance['sort'] );
290	$instance['display_author'] = $new_instance['display_author'];
291	$instance['personalize_results'] = $new_instance['personalize_results'];
292	$instance['img_src'] = trim( $new_instance['img_src'] );
293
294	return $instance;
295	}
296
297	/**
298	* Checks if both the Site ID and API secret settings are populated with
299	* non-empty values.
300	*
301	* @since 2.5.0
302	*
303	* @return bool True if Site ID and API Secret settings are set.
304	* False otherwise.
305	*/
306	private function site_id_and_secret_are_populated(): bool {
307	return $this->parsely->site_id_is_set() && $this->parsely->api_secret_is_set();
308	}
309
310	/**
311	* Returns all widget settings by assigning defaults if a setting isn't present
312	*
313	* @since 3.7.0
314	*
315	* @param array<string, mixed> $settings Widget Options.
316	* @return Widget_Settings
317	*/
318	public function get_widget_settings( array $settings ) {
319	/**
320	* Variable.
321	*
322	* @var Widget_Settings
323	*/
324	$widget_settings = $settings;
325
326	return array_merge( self::$default_widget_settings, $widget_settings );
327	}
328	}
329