html-templates.md

HTML Templates

An HTML template outputs a widget on the front end. The Widgets Bundle includes the template when it calls the widget's widget() method, so the template can use the widget's $instance and $args variables. The Widgets Bundle looks for tpl/default.php in your widget folder.

Override get_template_name() to use another template, and keep the template in the tpl folder at the root of the widget folder.

Example: Naming the Template

Override get_template_name():

function get_template_name( $instance ) {
	return 'my-awesome-template';
}

Then add the template, tpl/my-awesome-template.php:

<div>
	<?php echo $args['before_title'] . esc_html( $instance['title'] ) . $args['after_title']; ?>
	<div>
		<a href="<?php echo esc_url( $instance['link_url'] ); ?>"><?php echo esc_html( $instance['link_text'] ); ?></a>
	</div>
</div>

Choosing a Template From a Setting

get_template_name() receives the widget's $instance, so it can return a different template for each value of a setting.

Example: Choosing a Template

function get_template_name( $instance ) {
	$template_name = '';
	if ( ! empty( $instance['use_blue_template'] ) ) {
		$template_name = 'blue_template';
	} else {
		$template_name = 'red_template';
	}
	return $template_name;
}

Template Variables

Before the Widgets Bundle includes the template, SiteOrigin_Widget extracts the array that get_template_variables() returns into variables, so the template uses values you've already prepared, such as defaults for empty fields.

Example: Using Template Variables

Return the variables in an array:

function get_template_variables( $instance, $args ) {
	return array(
		'title'     => ! empty( $instance['title'] ) ? $instance['title'] : 'Default title',
		'link_url'  => ! empty( $instance['link_url'] ) ? $instance['link_url'] : '',
		'link_text' => ! empty( $instance['link_text'] ) ? $instance['link_text'] : 'Default link text.',
	);
}

Then use the variables in the template:

<div>
	<?php echo $args['before_title'] . esc_html( $title ) . $args['after_title']; ?>
	<div>
		<a href="<?php echo esc_url( $link_url ); ?>"><?php echo esc_html( $link_text ); ?></a>
	</div>
</div>

Escaping Output

Escape every value as late as possible, right before you output it, with the WordPress escaping functions, such as esc_html(), esc_url() and esc_attr(). Encode values for JavaScript with wp_json_encode(). The before_title and after_title values in $args hold HTML from the theme's widget area, so output them without escaping. Escaping Data on WordPress.org has the details.

Example: Escaping Values

<script type="text/javascript">
	var value = <?php echo wp_json_encode( $js_value ); ?>;
</script>
<div>
	<?php echo $args['before_title'] . esc_html( $title ) . $args['after_title']; ?>
	<div class="<?php echo esc_attr( $style_attribute ); ?>">
		<a href="<?php echo esc_url( $link_url ); ?>"><?php echo esc_html( $link_text ); ?></a>
	</div>
</div>