Our Goal<\/h2>\n
Learning by example is the most effective method, so let’s set a goal we want to achieve. A featured content widget is\u00a0be a good place to start. This widget would allow you to specify a title, add some text, an image and a link. This information would be presented in a nice way in the sidebar.<\/p>\n
The screenshots below show how this will all look when used in the new default Twenty Fifteen theme:<\/p>\n We’ll build the widget without the image capability first because it’s a bit simpler. Once we’ve figured everything else out we’ll add in the image to make\u00a0the widget\u00a0fully functional.<\/p>\n You can<\/em> add all the code in this article into your theme’s functions.php file but a widget really is something that should reside in a plugin. Creating one is pretty easy so let’s start with that!<\/p>\n First, create a folder in your Next, create the main plugin file within the folder. This should have the same name as the folder with a PHP extension: Open the new file and paste the following PHP comment. This is parsed by WordPress and the information within is used in the plugins section to list your plugin.<\/p>\n Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n At this stage you have a fully functioning plugin! It doesn’t do anything but it will be listed in the plugins section and can be activated. Let’s do so now.<\/p>\n If you want to learn more about creating plugins in general, take a look at our plugin development guide<\/a>.<\/p>\n Creating a WordPress widget takes four steps. We need to initialize and set up the widget, output a form in the backend, add any rules for processing the backend form and, finally, specify how the widget behaves on the front-end. These steps all translate to specific functions. Let’s look at the big picture by drawing up the structure of our code.<\/p>\n Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n Note that we are creating a class extending the You need to hook a function into The “mfc” part of my naming scheme refers to “My Featured Content.” This is called function prefixing and serves to create more unique function names to prevent naming collisions between different plugins.<\/p>\n Another tidbit which may help you is what a “method” and a “property” is. Functions contained within a class are referred to as methods. Variables defined within a class are called properties. There is no significant difference but it’s good to know so you don’t get confused by terminology.<\/p>\n The Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n When the user drags our widget into the sidebar they’ll be presented with a form, which is used to populate the front-end display. In our case we need fields for: The title, the description, the link text and link URL. We add the image in later.<\/p>\n The final version of the Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n The only reason this is so long is that we have four fields. We begin by determining the value of each field. The The reason we need these functions instead of just typing the names and ids ourselves is that there may be multiple instances of the same widget around. WordPress uses some built-in magic to manage all this for us. The final name of our input element may be The result of this code should be a form in the widgets section you can use to fill out the widget details.<\/p>\n Using the Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n This function is handy if you want to do something to the form data before saving it. A good example is the RSS widget. When you enter the RSS URL and save it, the most recent items are retrieved and cached. You could use the function to validate and sanitize URLs, numbers and other data as well.<\/p>\n Finally, the The function takes two arguments: The first one contains data about the widget area itself, and the second contains the instance variables of our widget.<\/p>\n When widget areas are set up a number of parameters are defined. The content to add before\/after the widget and before\/after the widget title is most prominent. To make sure your widgets play nice with other plugins and WordPress itself it is a good idea to use the following frame when creating plugins:<\/p>\n Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n Into this frame we add the value of the description field and the link, which we construct from the Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n Don’t forget to use string escaping functions, which serve to protect the data before it is served to the user. You can read more about this in the Validating, Sanitizing and Escaping User Data<\/a> article in the WordPress Codex. The result of our code should be the following:<\/p>\n You can use a number of methods to add an image. At the bare minimum this will require some JS and CSS, which means we’ll have to learn how to add those to widgets. We will be using WordPress’ built in media library function \u2013 no need to reinvent the wheel. If you’re building a custom solution, the methods of including JavaScript and stylesheets is almost exactly the same.<\/p>\n We need to enqueue scripts, just like we would do on the front-end or the WordPress admin. The actions to do this must be defined in the constructor function. Let’s add the following to it:<\/p>\n Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n If you’re not familiar with OOP (object oriented PHP) the notation may confuse you here. The second parameter of the The next step is to create the Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n Above, we’ve enqueued the The next step is to modify the backend form to add the image field. We need to figure out the value of the image field and output the controls for it, just like we did before:<\/p>\n Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n Note that this is very similar, the only addition is a button input with the class of Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n This bit of code will open up the media uploader screen when you click the button. Once you’ve chosen an image it will take the URL of the image and put it into the input element so it can be saved.<\/p>\n Finally, we need to use the value of our image field to output an image in the front-end. I added mine above the description like this:<\/p>\n![\"FInal](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2015\/02\/final.jpg\")
Creating a Plugin<\/h2>\n
wp-content\/plugins<\/code> directory and name it something unique. I’ll be using my-featured-content<\/code>.<\/p>\nmy-featured-content.php<\/code>.<\/p>\n![\"Backend](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2015\/02\/backend-widget.png\")
The Components of a Widget<\/h2>\n
WP_Widget<\/code> class. If you have no idea what this means, don’t worry, you don’t need to know any object oriented PHP to create a good widget. What you do need to know, though, is how to initialize the class.<\/p>\nwidgets_init<\/code> and from within that function use the register_widget()<\/code> function to initialize the widget by passing it the name of your class.<\/p>\nThe Widget Constructor<\/h3>\n
__construct()<\/code> method contains some basic information about the widget. The base class WP_Widget<\/code> takes care of the heavy lifting for is. By adding the code below into the constructor, our widget will show up in the widgets section.<\/p>\nThe Backend Form<\/h3>\n
form()<\/code> method is below. It’s quite long but don’t get to scared \u2013 I’ll explain everything underneath.<\/p>\n$instance<\/code> variable contains the values of our fields if they have already been saved. For each field we create a label and a user input element by using the get_field_name()<\/code> and get_field_id()<\/code> functions.<\/p>\nwidget-mfc_widget[2][link_url]<\/code> instead of just link<\/code>. This is how WordPress handles multiple widget areas, multiple sidebars and multiple widgets.<\/p>\n![\"Widget](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2015\/02\/widget_form.jpg\")
Handling Form Data<\/h3>\n
update()<\/code> function we can determine what happens to our form data before it is saved. We actually don’t need anything special so our final function will look like this:<\/p>\nDisplaying The Widget<\/h3>\n
widget()<\/code> function displays our widget. You can add any HTML here and it will be output in the sidebar.<\/p>\nlink_url<\/code> and link_title<\/code> fields, something like this:<\/p>\n![\"Featured](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2015\/02\/Screen-Shot-2015-02-23-at-13.57.49.png\")
Adding An Image<\/h2>\n
add_action()<\/code> function is usually a string which indicated the function that is called. The same thing is happening here but we are indicating that we want the mfc_assets()<\/code> function from within our class, not the global scope.<\/p>\nmfc_assets()<\/code> function inside our class and enqueue the necessary scripts and styles within it.<\/p>\nmedia-upload<\/code> and thickbox<\/code> scripts. These are included within WordPress and\u00a0are the basic components of the media dialogue. We also include our own mfc-media-upload.js<\/code> file, which is a very simple JavaScript file that governs our upload process (more on this in a second). Last, but not least, the style required for the thickbox<\/code> functionality is also enqueued.<\/p>\nupload_image_button<\/code>. Our Javascript will detect when this button is pressed so we can select an image. Create a new file in the directory of your plugin, name it mfc-media-upload.js<\/code>. The code you will need to paste inside is the following:<\/p>\n
![\"Featured](\"https:\/\/wpmudev.com\/blog\/wp-content\/uploads\/2015\/02\/Screen-Shot-2015-02-23-at-14.27.40.png\")