Custom Layouts

There are a number of hooks available for creating a custom layouts of news stories. These include:

• ucf_events_display_layoutslug_before
• ucf_events_display_layoutslug_title
• ucf_events_display_layoutslug
• ucf_events_display_layoutslug_after

Each hook is dynamically called depending on the slug of the layout. So the 'classic' layout hooks would all start with ucf_events_display_classic.

Special Note on $items Variable

It was brought to our attention in issue #2 that when a feed only contains 1 event, the display of the events would break. We were able to track down a strange behavior in WordPress's do_action function where the 2nd variable is dereferenced if it is an array containing only 1 index. To avoid this problem, all the examples below add an additional step where the variable $items is cast back into an array if it is not an array. This step is not really necessary if the $items variable is never used.

ucf_events_display_layoutslug_before

This hook is responsible for the markup immediately before the title. It is recommended that any wrapper divs or content that needs to be above the title be placed here.

Parameters

$items: Array|Object | $title: String | $display_type: String

Example

if ( !function_exists( 'ucf_events_display_classic_before' ) ) {
	function ucf_events_display_classic_before( $items, $title, $display_type ) {
		ob_start();
	?>
		<div class="ucf-events ucf-events-classic">
	<?php
		echo ob_get_clean();
	}
	add_action( 'ucf_events_display_classic_before', 'ucf_events_display_classic_before', 10, 3 );
}

---

ucf_events_display_layoutslug_title

This hook is responsible for displaying the title. Logic for displaying the title differently (e.g. using the pre-formatted widget title) should be handled here.

Parameters

$items: Array|Object | $title: String | $display_type: String

Example

if ( !function_exists( 'ucf_events_display_classic_title' ) ) {
	function ucf_events_display_classic_title( $items, $title, $display_type ) {
		$formatted_title = $title;

		switch ( $display_type ) {
			case 'widget':
				// title is already formatted at the widget level
				break;
			case 'default':
			default:
				$formatted_title = '<h2 class="ucf-events-title">' . $title . '</h2>';
				break;
		}
		echo $formatted_title;
	}
	add_action( 'ucf_events_display_classic_title', 'ucf_events_display_classic_title', 10, 3 );
}

---

ucf_events_display_layoutslug

This function is responsible for displaying the event items themselves. This is where the primary display loop should happen.

Parameters

$items: Array|Object | $title: String | $display_type: String

Example

if ( !function_exists( 'ucf_events_display_classic' ) ) {
	function ucf_events_display_classic( $items, $title ) {
		if ( ! is_array( $items ) ) { $items = array( $items ); }
		ob_start();
	?>
		<div class="ucf-events-list">

		<?php if ( $items ): ?>
			<div class="ucf-events-subheadings ucf-event-row">
				<div class="ucf-event-col ucf-event-when">
					<strong class="events-subheading">Date</strong>
				</div>
				<div class="ucf-event-col ucf-event-content">
					<strong class="ucf-events-subheading">Description</strong>
				</div>
			</div>

			<?php
			foreach( $items as $event ) :
				$starts = new DateTime( $event->starts );
			?>
			<div class="ucf-event ucf-event-row">
				<div class="ucf-event-col ucf-event-when">
					<time class="ucf-event-start-datetime" datetime="<?php echo $starts->format( 'c' ); ?>">
						<span class="ucf-event-start-date"><?php echo $starts->format( 'M j' ); ?></span>
						<span class="ucf-event-start-time"><?php echo $starts->format( 'g:i a' ); ?></span>
					</time>
				</div>
				<div class="ucf-event-col ucf-event-content">
					<a class="ucf-event-title" href="<?php echo $event->url; ?>">
						<?php echo $event->title; ?>
					</a>
					<a class="ucf-event-location" href="<?php echo $event->location_url; ?>">
						<?php echo $event->location; ?>
					</a>
				</div>
			</div>
			<?php endforeach; ?>

		<?php else: ?>
			<span class="ucf-events-error">No events found.</span>
		<?php endif; ?>

		</div>
	<?php
		echo ob_get_clean();
	}
	add_action( 'ucf_events_display_classic', 'ucf_events_display_classic', 10, 3 );
}

---

ucf_events_display_layoutslug_after

This hook is responsible for displaying any markup after the news stories. Use this to close out divs opened up in the ucf_events_display_layoutslug_before function.

Parameters

$items: Array|Object | $title: String | $display_type: String

Example

if ( !function_exists( 'ucf_events_display_classic_after' ) ) {
	function ucf_events_display_classic_after( $items, $title ) {
		ob_start();
	?>
		</div>
	<?php
		echo ob_get_clean();
	}
	add_action( 'ucf_events_display_classic_after', 'ucf_events_display_classic_after', 10, 3 );
}

ucf_events_get_layouts

This hook is responsible for adding the layout to the array of registered layouts. This array is used to populate the dropdown list in the widget.

Parameters

$layouts: Array

Example

if ( ! function_exists( 'add_classic_layout' ) ) {
	function add_classic_layout( $layouts ) {
		$layouts['classic'] = 'Classic Layout';
		return $layouts;
	}

	add_action( 'ucf_events_get_layouts', 'add_classic_layout', 10, 1 );
}