Square Candy ACF Events

A custom events plugin using Advanced Custom Fields

• Requires Advanced Custom Fields Pro 5.x
• Outputs HTML including schema.org structured data
• A basic, easy to use events system

Settings

• See available settings at Events > Event Settings
  • Date formatting options
  • Google Maps API key integration
  • Additional Mapping options
  • Display options

Shortcodes

Default:

Show Upcoming Events in the standard format

[squarecandy_events]
or
echo squarecandy_events_func();

Archive:

Show Past Events in the standard format

[squarecandy_events type=past]
or
echo squarecandy_events_func( array('type'=>'past') );

All:

Show All Events (past, present and future) in the standard format

[squarecandy_events type=all]
or
echo squarecandy_events_func( array('type'=>'all') );

Compact:

Show the compact events block. This is good for sidebars, a homepage block, or other place where a compact preview of upcoming events is needed.

[squarecandy_events style=compact]
or
echo squarecandy_events_func( array('style'=>'compact') );

Category Filter:

Filter the list by Event Category. The example below assumes you have already created an event category called "My Example Category" and applied that category to some event items.

[squarecandy_events cat=my-example-category]
or
echo squarecandy_events_func( array('cat'=>'my-example-category') );

Combinations:

Combine any of the above as needed...

[squarecandy_events type=past style=compact cat=my-example-category]

Advanced:

More options are now available:

• not_in=123,125,127 // filter out specific events by ID
• posts_per_page=3 // override total posts returned
• only_featured=true // filter for featured posts only
• featured_at_top=true // order featured posts at top
• exclude_featured=true // filter out featured posts
• more_info_post_link=true // force the more info button to appear by default & link to the single post instead of to an external website

Filters

Available filters:

• squarecandy_filter_events_fields - filter the ACF fields array
• squarecandy_filter_events_supports - filter the array of components the post type supports ( 'title', 'editor', 'author', 'thumbnail' )

Fields/Meta Guide

post_type = 'event'

featured - bool - Featured Event or no start_date - stored as ? displayed as F j, Y all_day - bool multi_day - bool start_time - stored as ? displayed as g:i a end_date end_time venue - text address - text city - text state - text zip - text country - select venue_location - google_map - optional if google maps api zoom_level - range - optional if google maps api more_info_link - url tickets_link - url facebook_link - url short_description - wysiwyg category - taxonomy (events-category) save_terms = 1 archive_date - autogenerated Y-m-d H:i:s sort_date - autogenerated Y-m-d H:i:s magic_sort_date - autogenerated Y-m-d H:i:s featured_works - post_object - optional - if works plugin active

Developer Guide

For more detailed information about coding standards, development philosophy, how to run linting, how to release a new version, and more, visit the Square Candy Developer Guide Wiki.

Roadmap

• add cancelled feature and corresponding schema https://schema.org/EventCancelled
• add online location feature https://schema.org/VirtualLocation https://schema.org/BroadcastEvent
• install Gamajo and make single template overridable
• refactor item previews to use an overridable template file, but don't break shortcodes in the process.
• past events accordions: refactor for less queries
• past events accordions: offer ASC and DESC year sorting
• past events accordions: offer ASC and DESC item sorting within each year
• past events accordions: accessibility fixes for accordion feature
• page-per-year archive: SEO fixes for single year past https://example.com/events/2022/ - add year to title, unique description.
• refactor button icons and labels: make consistent between preview and single; icons always optional; FA6 compatible; etc
• consider a full refactor of external links? replace More Info/Tickets/Facebook fields with a repeater to allow for any amount/kind of external link.
• refactor/rethink: "MORE INFO" button in preview links to single view; "MORE INFO" button in single links to external URL; "MORE INFO" is generic and not accessible.
• accessibility review for entire system
• Check if any clients are using the Google Maps integration anymore. Remove the feature and the code if not.
• Create a v2 css option with a better basic/default look and CSS variables where appropriate.
• Support more preview image positions (left, right, top)
• Improve "add to calendar" to include more than Google.
• make options for both "past" and "all" to be grouped by year independently
• Consider performance limits for all past/archive options (full Past shortcode, Past shortcode with year accordions, page-per-year archives). Implement pagination, AJAX or load-more solutions past reasonable limitations.

done

• create hidden takedown/archive date for smoother queries
• throw error if end date is before start date