Widgets

Unlike post types and taxonomies, widgets have a more complex structure within the Rila Framework.

There are two classes that handle widgets:

1. Rila\Widget handles dictionaries, data mapping and etc., as it extends Rila\Item.
2. Rila\Custom_Widget, which extends WP_Widget and handles the widget forms, data and display.

The good news is that you only need to use the Custom_Widget class, as it provides some basic functionality and encapsulates the WP_Widget class.

Creating a widget

Normal widgets in WordPress are registered on the widgets_init hook, which is the one you need too. As widgets are different classes in their core, you need to extend Rila\Custom_Widget in order to create one for yourself:

add_action( 'widgets_init', 'mytheme_register_widgets' );
function mytheme_register_widgets() {
	class MyTheme_Custom_Widget extends Rila\Custom_Widget {
		
	}
}

Initializing the widget

Your custom widget needs many details like title, description and etc. With Custom_Widget you need to declare a function called initialize, where you simply use the $this object to add all necessary details:

function initialize() {
	/**
	 * You need to set a title for the widget.
	 * 
	 * If one is not provided, the framework will use the class name, so
	 * "MyTheme_Custom_Widget" would be transformed to "MyTheme Custom Widget".
	 */
	$this->title = 'Custom Widget';

	/**
	 * It's recommended to set a description, which lets users know what
	 * the widget can do for them.
	 */
	$this->description = 'A widget that is handled through the Rila Framework';

	/**
	 * There is an internal array with CSS classes, where you can add custom ones.
	 */
	$this->css_class[] = 'custom-widget';

	/**
	 * This width controls the size of the widget editor in the backend.
	 */
	$this->width = 500;

	/**
	 * You can directly map values here.
	 */
	$this->map(array(
		/* .. */
	));

	/**
	 * Add ACF fields to the widget.
	 */
	$this->fields = array(
		/* .. */
	);
}

Rendering the widget

You also need to display the widget in the front-end.

function render( $widget ) {
	echo rila_view( 'test-custom' )
		->with( 'widget', $widget );
}

As you can see, the method looks a lot like a normal page template.

What is specific here is that you need to pass the $widget object to the context. Afterwards, if you have a field which is called title, you can use it like this within the template:

{{ widget.title }}

Full example:

add_action( 'widgets_init', 'mytheme_register_widgets' );
function mytheme_register_widgets() {
	class MyTheme_Custom_Widget extends Rila\Custom_Widget {
		function initialize() {
			$this->title = 'Custom Widget';
			$this->description = 'A widget that is handled through the Rila Framework';
			$this->css_class[] = 'custom-widget';
			$this->width = 500;
			$this->map(array(
				'title' => 'wp_kses_post'
			));
		}


		function render( $widget ) {
			echo rila_view( 'test-custom' )
				->with( 'widget', $widget );
		}
	}
}

Custom forms

By default, the form method of Custom_Widget does not do anything, as most people would use a plugin for Custom Fields to add fields to the widget. Currently, you can use the fields property in initialize() in order to auto-register fields to that widget.

If you want to create your own form and save methods, you can learn how to do it at the Widgets API page on the WordPress codex.

---

Next article: Queries and pagination