Tidied up code comments pre-release.

This commit is contained in:
ekes 2019-05-12 15:37:07 +02:00
parent eab5592dd5
commit 65db102f6f
4 changed files with 224 additions and 81 deletions

View file

@ -1,11 +1,35 @@
<?php <?php
/**
* Squat Radar Connector.
*
* Fetch data from Radar API.
*
* @package squat-radar
* @since 2.0.0
*/
// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;
class Squat_Radar_Connector { class Squat_Radar_Connector {
const BASE_URL = 'https://radar.squat.net'; const BASE_URL = 'https://radar.squat.net';
const API_EVENTS = '/api/1.2/search/events.json'; const API_EVENTS = '/api/1.2/search/events.json';
/**
* Retrieve array of events from API based on a query.
*
* @see self::encode_api_query() for $query values.
*
* @param array $query
* Key value pairs for the API query.
*
* @return array
* Array of events.
*
* @throws Squat_Radar_Connector_Exception
* When events are not returned, but a timeout or API error.
*/
function get_events( $query ) { function get_events( $query ) {
$url = self::BASE_URL . self::API_EVENTS . '?' . build_query( $query ); $url = self::BASE_URL . self::API_EVENTS . '?' . build_query( $query );
@ -21,6 +45,15 @@ class Squat_Radar_Connector {
} }
/**
* Turn a Radar frontend Search URL into facets key value and language values.
*
* @param string $url
* The https://radar.squat.net/events filtered URL.
*
* @return array
* [ 'language' => language code, 'facets' => [key => value] ].
*/
function decode_search_url( $url ) { function decode_search_url( $url ) {
$matches = []; $matches = [];
$result = []; $result = [];
@ -36,6 +69,21 @@ class Squat_Radar_Connector {
return $result; return $result;
} }
/**
* Encode a query key value from facets, fields, language, limit.
*
* @param array $facets
* Optional. Facet key => filter value array.
* @param array $fields
* Optional. Index array of API field names to retrieve.
* @param string $language
* Optional. Language code.
* @param int $limit
* Optional. Maximum number to items to return.
*
* @return array
* Array for use in self::get_events().
*/
function encode_api_query( $facets = [], $fields = [], $language = '', $limit = 10 ) { function encode_api_query( $facets = [], $fields = [], $language = '', $limit = 10 ) {
$query = []; $query = [];
@ -57,6 +105,25 @@ class Squat_Radar_Connector {
return $query; return $query;
} }
/**
* Return events meeting argument criteria. Either from cache, or retrieved from API.
*
* @param array $facets
* Facet name key => filter value.
* @param array $fields
* Optional. Array of key names.
* @param string $language
* Optional. Language code.
* @param int $limit
* Maximum number of items to return.
* @param int $expiration
* Seconds to cache results. 0 never expires.
* @param bool $reset
* Force a cache reset.
*
* @return array
* Array of event arrays, values keyed by field name.
*/
function events( $facets, $fields = [], $language = NULL, $limit = 10, $expiration = 10800, $reset = FALSE ) { function events( $facets, $fields = [], $language = NULL, $limit = 10, $expiration = 10800, $reset = FALSE ) {
// Fields we often want to get data out of but not necessarily are chosen to be shown. // Fields we often want to get data out of but not necessarily are chosen to be shown.
$fields = array_merge($fields, ['uuid', 'title', 'body:value', 'url', 'event_status']); $fields = array_merge($fields, ['uuid', 'title', 'body:value', 'url', 'event_status']);

View file

@ -1,7 +1,27 @@
<?php <?php
/**
* Squat Radar Events Formatter.
*
* Provides filters to format the output of Squat Radar Events.
*
* 'squat_radar_format_event' allows the whole event to be formatted.
* Default filter Squat_Radar_Formatter::format_event().
*
* 'squat_radar_field_html' formats individual fields.
* Basic implementation Squat_Radar_Formatter::field_html().
*
* @package squat-radar
* @since 2.0.0
*/
// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;
class Squat_Radar_Formatter { class Squat_Radar_Formatter {
/**
* Register filters with Wordpress.
*/
static public function register() { static public function register() {
// Filter to go through fields and then call filters to turn these into HTML. // Filter to go through fields and then call filters to turn these into HTML.
add_filter('squat_radar_format_event', [__CLASS__, 'format_event'], 10, 3); add_filter('squat_radar_format_event', [__CLASS__, 'format_event'], 10, 3);
@ -28,6 +48,20 @@ class Squat_Radar_Formatter {
add_filter('squat_radar_field_html', [__CLASS__, 'field_title_html'], 15, 4); add_filter('squat_radar_field_html', [__CLASS__, 'field_title_html'], 15, 4);
} }
/**
* Implementation of 'squat_radar_format_event'.
*
* Formats an API event array into HTML.
*
* @param array $event
* The event array from the API. Nested field names with values.
* @param array $fields
* The field names required for display. Colons used to denote nesting.
* @param array $context
*
* @return string
* HTML.
*/
static public function format_event($event, $fields, $context) { static public function format_event($event, $fields, $context) {
$context['event'] = $event; $context['event'] = $event;
@ -45,6 +79,74 @@ class Squat_Radar_Formatter {
} }
/**
* Basic implementation of 'squat_radar_field_html' filter.
*
* Put the output into HTML.
*
* @param array|string $value
* The field value being manipulated to become HTML to be displayed.
* @param array|string $original
* The original value of the field before any changes by filters.
* @param array $field
* The field tree. $field[0] being the name of the present field. $field[1]
* being any parent etc.
* @param array $context
*
* @return string
* Flattend array with additional default classes.
*/
static public function field_html($value, $original, $field, $context) {
if ($value != $original) {
return $value;
}
if (is_array($value)) {
if ( ! empty($value['value']) ) {
$value = $value['value'];
}
elseif ( ! empty($value['title']) ) {
$value = $value['title'];
}
elseif ( ! empty($value['name']) ) {
$value = $value['name'];
}
elseif ( ! empty($value[0]['value']) ) {
foreach ($value as $row) {
$values[] = $row['value'];
}
$value = $values;
}
elseif ( ! empty($value[0]['title']) ) {
foreach ($value as $row) {
$titles[] = $row['title'];
}
$value = $titles;
}
elseif ( ! empty($value[0]['name']) ) {
foreach ($value as $row) {
$names[] = $row['name'];
}
$value = $names;
}
}
if (is_array($value)) {
$output = '<ul class="squat-radar-' . sanitize_html_class($field[0]) . ' squat-radar-list">';
foreach ($value as $row) {
$output .= '<li class="squat-radar-item-' . sanitize_html_class($field[0]) . '">' . sanitize_text_field( $row ) . '</li>';
}
$output .= '</ul>';
return $output;
}
else {
$value = '<span class="squat-radar-' . sanitize_html_class($field[0]) . '">' . wp_kses_post( $value ) . '</span>';
}
return $value;
}
/** /**
* Date field formatting implementation of 'squat_radar_field_html' filter. * Date field formatting implementation of 'squat_radar_field_html' filter.
*/ */
@ -257,11 +359,10 @@ class Squat_Radar_Formatter {
return $value; return $value;
} }
/** /**
* Format image implementation of 'squat_radar_field_html' filter. * Format image implementation of 'squat_radar_field_html' filter.
* *
* Deliberatly run after field_link_html. Showing how to override an existing filter. * Intentionally run after field_link_html. Showing how to override an existing filter.
* image:file:url * image:file:url
*/ */
static public function field_image_html($value, $original, $field, $context) { static public function field_image_html($value, $original, $field, $context) {
@ -272,76 +373,9 @@ class Squat_Radar_Formatter {
return $value; return $value;
} }
/**
* Basic implementation of 'squat_radar_field_html' filter.
*
* Put the output into HTML.
*
* @param array|string $value
* The field value being manipulated to become HTML to be displayed.
* @param array|string $original
* The original value of the field before any changes by filters.
* @param array $field
* The field tree. $field[0] being the name of the present field. $field[1]
* being any parent etc.
* @param array $context
*
* @return string
* Flattend array with additional default classes.
*/
static public function field_html($value, $original, $field, $context) {
if ($value != $original) {
return $value;
}
if (is_array($value)) {
if ( ! empty($value['value']) ) {
$value = $value['value'];
}
elseif ( ! empty($value['title']) ) {
$value = $value['title'];
}
elseif ( ! empty($value['name']) ) {
$value = $value['name'];
}
elseif ( ! empty($value[0]['value']) ) {
foreach ($value as $row) {
$values[] = $row['value'];
}
$value = $values;
}
elseif ( ! empty($value[0]['title']) ) {
foreach ($value as $row) {
$titles[] = $row['title'];
}
$value = $titles;
}
elseif ( ! empty($value[0]['name']) ) {
foreach ($value as $row) {
$names[] = $row['name'];
}
$value = $names;
}
}
if (is_array($value)) {
$output = '<ul class="squat-radar-' . sanitize_html_class($field[0]) . ' squat-radar-list">';
foreach ($value as $row) {
$output .= '<li class="squat-radar-item-' . sanitize_html_class($field[0]) . '">' . sanitize_text_field( $row ) . '</li>';
}
$output .= '</ul>';
return $output;
}
else {
$value = '<span class="squat-radar-' . sanitize_html_class($field[0]) . '">' . wp_kses_post( $value ) . '</span>';
}
return $value;
}
/** /**
* Title field HTML implentation of 'squat_radar_field_html' filter. * Title field HTML implementation of 'squat_radar_field_html' filter.
*/ */
static public function field_title_html($value, $original, $field, $context) { static public function field_title_html($value, $original, $field, $context) {
if (($field[0] == 'title' || $field[0] == 'title_field') && count($field) == 1) { if (($field[0] == 'title' || $field[0] == 'title_field') && count($field) == 1) {

View file

@ -1,11 +1,12 @@
<?php <?php
/** /**
* Manage the Squat Radar plugin. * Manage the Squat Radar plugin.
* *
* @package Squat_Radar * @package squat-radar
* @since 2.0.0
*/ */
// Exit if accessed directly.
defined( 'ABSPATH' ) || exit; defined( 'ABSPATH' ) || exit;
/** /**
@ -38,14 +39,15 @@ class Squat_Radar_Instance {
} }
/** /**
* Load translation files * Load translation files.
*
* @since 0.2.4
*/ */
function i18n() { function i18n() {
load_plugin_textdomain( 'squat-radar', false, '/languages' ); load_plugin_textdomain( 'squat-radar', false, '/languages' );
} }
/**
* Shortcode callback to print the dynamic sidebar.
*/
function print_sidebar() { function print_sidebar() {
ob_start(); ob_start();
@ -56,8 +58,9 @@ class Squat_Radar_Instance {
return ob_get_clean(); return ob_get_clean();
} }
/**
* Action callback to add the dynamic sidebar.
*/
function add_sidebar() { function add_sidebar() {
register_sidebar([ register_sidebar([

View file

@ -1,5 +1,13 @@
<?php <?php
/**
* Squat Radar Events Widget.
*
* @package squat-radar
* @since 2.0.0
*/
// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;
class Squat_Radar_Widget extends WP_Widget { class Squat_Radar_Widget extends WP_Widget {
@ -28,15 +36,26 @@ class Squat_Radar_Widget extends WP_Widget {
add_option( 'squat_radar_widget_cron_run', []); add_option( 'squat_radar_widget_cron_run', []);
} }
/**
* Enqueue scripts callback, add CSS.
*/
static public function widget_style() { static public function widget_style() {
wp_register_style( 'squat-radar-widget', SQUAT_RADAR_URL . '/assets/squat-radar.css' ); wp_register_style( 'squat-radar-widget', SQUAT_RADAR_URL . '/assets/squat-radar.css' );
wp_enqueue_style( 'squat-radar-widget' ); wp_enqueue_style( 'squat-radar-widget' );
} }
/**
* Enqueue scripts callback, add JS.
*/
static public function widget_script() { static public function widget_script() {
wp_register_script( 'squat-radar-widget', SQUAT_RADAR_URL . '/assets/squat-radar.js', ['jquery'] ); wp_register_script( 'squat-radar-widget', SQUAT_RADAR_URL . '/assets/squat-radar.js', ['jquery'] );
} }
/**
* Cron action.
*
* Uses an option to keep track of when run, and updates any (experimental) widgets that update using a cron period instead of ajax.
*/
public static function cache_cron() { public static function cache_cron() {
$now = time(); $now = time();
$last_run = get_option('squat_radar_widget_cron_run', []); $last_run = get_option('squat_radar_widget_cron_run', []);
@ -50,6 +69,9 @@ class Squat_Radar_Widget extends WP_Widget {
set_option('squat_radar_widget_cron_run', $last_run); set_option('squat_radar_widget_cron_run', $last_run);
} }
/**
* Refresh an individual widget instance for cache_cron().
*/
protected static function cache_refresh($instance) { protected static function cache_refresh($instance) {
$connector = new Squat_Radar_Connector(); $connector = new Squat_Radar_Connector();
@ -58,6 +80,7 @@ class Squat_Radar_Widget extends WP_Widget {
$languages = array_merge($instance['url']['keys']['language'], (array) $languages); $languages = array_merge($instance['url']['keys']['language'], (array) $languages);
foreach ($languages as $language) { foreach ($languages as $language) {
try { try {
// Force update. Don't set expire.
$data = $connector->events($instance['url']['keys']['facets'], $instance['fields'], $language, $instance['limit'], 0, TRUE ); $data = $connector->events($instance['url']['keys']['facets'], $instance['fields'], $language, $instance['limit'], 0, TRUE );
} }
catch ( Squat_Radar_Connector_Exception $e ) { catch ( Squat_Radar_Connector_Exception $e ) {
@ -68,7 +91,11 @@ class Squat_Radar_Widget extends WP_Widget {
return TRUE; return TRUE;
} }
/**
* Implementation of WP_Widget::widget().
*
* Outputs the events for the correct instance of the widget.
*/
public function widget( $args, $instance ) { public function widget( $args, $instance ) {
$widget_id = 'squat_radar_widget_' . $this->number; $widget_id = 'squat_radar_widget_' . $this->number;
@ -104,6 +131,9 @@ class Squat_Radar_Widget extends WP_Widget {
echo $args['after_widget']; echo $args['after_widget'];
} }
/**
* Action callback for AJAX widget display.
*/
public static function ajax_callback() { public static function ajax_callback() {
if ( ! array_key_exists('instance', $_POST) ) { if ( ! array_key_exists('instance', $_POST) ) {
wp_die(); wp_die();
@ -138,6 +168,11 @@ class Squat_Radar_Widget extends WP_Widget {
return $html; return $html;
} }
/**
* Implementation of WP_Widget::form().
*
* Widget options.
*/
public function form( $instance ) { public function form( $instance ) {
// //
@ -269,7 +304,11 @@ class Squat_Radar_Widget extends WP_Widget {
} }
/**
* Implementation of WP_Widget::update().
*
* Save widget options.
*/
public function update( $new_instance, $old_instance ) { public function update( $new_instance, $old_instance ) {
$options = []; $options = [];