Sometimes you just can’t find a pre-built widget that does exactly what you want, when you run into this scenario, your best bet is to build something from scratch. This tutorial will is an answer to “How do I build a custom WordPress widget?“.
WordPress widgets are objects that have several required parts:
- Constructor (__construct) – actions to take when the widget is first created like enqueueing javascript or stylesheet files.
- Front-end (widget) – the widget’s HTML output
- Back-end (form) – the form for the widget’s edit interface in the Admin section
- Update (update) – catches the form submission from the back-end form, updating the database
The easiest way to add a custom widget type to your theme is to build a class that looks something like this:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 |
<?php /* Plugin Name: A Widget Plugin URI: https://joshrichet.com Description: A Hello World Widget Tutorial Author: Josh Richet Version: 1.0 Author URI: https://joshrichet.com */ // Block direct requests if ( !defined('ABSPATH') ) die('-1'); add_action( 'widgets_init', function(){ register_widget( 'A_Widget' ); }); /** * Adds A_Widget widget. I would rename this class when using this code as a template. */ class A_Widget extends WP_Widget { /** * Register widget with WordPress. */ function __construct() { parent::__construct( 'A_Widget ', // Base ID __('Hello World Widget', 'text_domain'), // Name array( 'description' => __( 'Widget Tutorial!', 'text_domain' ), ) // Args ); } /** * Front-end display of widget. * * @see WP_Widget::widget() * * @param Array $args Widget arguments. * @param Array $instance Saved values from database. */ public function widget( $args, $instance ) { echo $args['before_widget']; if ( ! empty( $instance['title'] ) ) { echo $args['before_title'] . apply_filters( 'widget_title', $instance['title'] ). $args['after_title']; } echo __( 'Hello, World!', 'text_domain' ); echo $args['after_widget']; } /** * Back-end widget form. * * @see WP_Widget::form() * * @param array $instance Previously saved values from database. */ public function form( $instance ) { if ( isset( $instance[ 'title' ] ) ) { $title = $instance[ 'title' ]; } else { $title = __( 'New title', 'text_domain' ); } ?> <p> <label for="<?php echo $this->get_field_id( 'title' ); ?>"><?php _e( 'Title:' ); ?></label> <input class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" name="<?php echo $this->get_field_name( 'title' ); ?>" type="text" value="<?php echo esc_attr( $title ); ?>"> </p> <?php } /** * Clean form values as they are saved. * * @see WP_Widget::update() * * @param array $new_instance Values just sent to be saved. * @param array $old_instance Previously saved values from database. * * @return array Updated safe values to be saved. */ public function update( $new_instance, $old_instance ) { $instance = array(); $instance['title'] = ( ! empty( $new_instance['title'] ) ) ? strip_tags( $new_instance['title'] ) : ''; return $instance; } } // class A_Widget |
To embed this widget type into your own custom theme, just include this php in your functions.php
To add this widget type to your custom plugin, include this code in a standard plugin file.