{"id":141266,"date":"2015-05-24T08:00:49","date_gmt":"2015-05-24T12:00:49","guid":{"rendered":"http:\/\/premium.wpmudev.org\/blog\/?p=141266"},"modified":"2015-05-23T18:33:59","modified_gmt":"2015-05-23T22:33:59","slug":"author-list-widget","status":"publish","type":"post","link":"https:\/\/wpmudev.com\/blog\/author-list-widget\/","title":{"rendered":"How to Create a Custom Author List Widget in WordPress"},"content":{"rendered":"

For many websites good authors are the<\/em> most important asset they have. Showcasing them properly can be an important concern and WordPress doesn’t really have anything powerful out-of-the-box. Most of the widgets in the WordPress Plugin Directory\u00a0are a little basic so I thought it would be a good idea to create something really powerful myself.<\/p>\n

In this Weekend WordPress Project\u00a0I’ll show you how you can create your own\u00a0\u2013 simpler \u2013\u00a0widget, and then I’ll show you the actual plugin I adopted in the directory\u00a0and how I\u00a0added versatile features to make it as flexible as possible for others.<\/p>\n

Let’s get started.<\/p>\n

Creating Our Own Widget<\/h2>\n

Let’s start by doing things on our own. This requires creating a plugin<\/a> and \u2013 within it \u2013\u00a0creating a widget<\/a>. Here’s the nutshell version of the two linked articles:<\/p>\n

    \n
  1. Create a folder in your wp-content\/plugins<\/code> folder – name it my-author-list<\/code><\/li>\n
  2. Within this folder create a file named my-author-list.php<\/code>, this will be your main plugin file<\/li>\n
  3. Paste the following code within it (feel free to replace the author info in there)<\/li>\n<\/ol>\n
    Loading gist b8cc9371321b2fc74e60554c4968c9dd<\/a>

    Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n

    At this stage, you have made a fully functional plugin, although it doesn’t do anything yet apart from show up in the backend. Go ahead and activate it now.<\/p>\n

    Next, let’s paste the skeleton code we’ll need to make a widget. Add the following to the file:<\/p>\n

    Loading gist 250ce27c2fb54ce539c00927c6e0468b<\/a>

    Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n

    To create a widget you need to extend the WP_Widget<\/code> with your own sub-class. Within this sub-class you need to define a few functions, which govern how the widgets work. Don’t worry if you don’t know what classes are, the syntax is pretty simple.<\/p>\n

    All you need to know is what those four functions in there do and you can code within them throughout this exercise. The __construct()<\/code> function basically adds our widget to WordPress. It contains the name, description and a few other details of the widget.<\/p>\n

    The form()<\/code> function governs the backend form, which shows up when you add the widget to a widget area. This is where you can create inputs for additional options, like how many authors to show, the widget title, and so on.<\/p>\n

    The widget()<\/code> function takes care of the front-end display. Any code in there will be shown where the widget is supposed to be on our page.<\/p>\n

    The update()<\/code> function will not necessarily be needed, in fact, in this example we can discard it. This function can process data that is submitted when the widget is saved in the backend. This is great for retrieving API data based on the user input or perhaps transforming the input itself. I’ll discard this for now since we don’t need it.<\/p>\n

    Adding Widget Options<\/h3>\n

    Let’s stick to the basics for now. A simple widget title, author count, order by and order direction field should do. I like to take the following steps for each.<\/p>\n

      \n
    1. Determine the current value for each field<\/li>\n
    2. Determine the possible values for dropdowns, radio or checkboxes<\/li>\n
    3. Output the field<\/li>\n<\/ol>\n

      Here’s the code I would use for the three fields we discussed:<\/p>\n

      Loading gist 42df9f34d246ae9504625fe7f68a282a<\/a>

      Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n

      The $instance<\/code> variable holds the current value of the fields, ie: the values the user has saved. In the first block I check those values. If they are empty I set a default for each field. Next up are field options.<\/p>\n

      For each field where I have a pre-set number of options I create an array for them. This may seem a little redundant for the order field but it makes the field output code more modular and it is also easier to handle the currently selected value.<\/p>\n

      Next up are the fields. They are perfectly normal HTML fields, the only two things you need to remember are to use the $this->get_field_name()<\/code> and $this->get_field_id()<\/code> methods. These are needed for WordPress to be able to save our data to the correct widget. Other than that, all the code is simple HTML and PHP loops.<\/p>\n

      At this stage you should be able to drag the widget into any widget area and save its data.<\/p>\n

      Displaying Our Widget<\/h3>\n

      When displaying a widget you should always be mindful of its surroundings. When a widget are is defined using the reregister_sidebar()<\/code><\/a> function a number of parameters can be defined such as before_title<\/code> and before_widgets<\/code>. These are passed as the first parameter for our widget()<\/code> function, the second parameter holds the widget’s instance variables, the saved data for the widget.<\/p>\n

      This is why almost all widget display functions should use the following skeleton code:<\/p>\n

      Loading gist 2433331b8818803c042b96cac46784ba<\/a>

      Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n

      This code will display any code that is supposed to precede and succeed the widget as well as any code that should be added before the title, the title itself and any code after the title.<\/p>\n

      Getting Authors<\/h3>\n

      We’ll be using the get_users()<\/code><\/a> function to retrieve our authors, all we need to do is pass our parameters to it. Here’s the code, which should be pasted inside the widget display skeleton where it says “\/\/ Main Widget Code Here”:<\/p>\n

      Loading gist 0c7db01d8ecf2137362a9e95d686897f<\/a>

      Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n

      The $users<\/code> variable should contain an array of user objects. We now need to cycle through them using a simple loop and display any information we want. Here’s an example which shows the avatar and the user’s name, each linking to the user’s url. Paste the code right below the call to the get_users<\/code> function.<\/p>\n

      Loading gist 18020957353f7efa0428ccd0dcd1b068<\/a>

      Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n

      Now you should see a list of users, which you can control using the settings defined in the widget. It won’t look super awesome, but we can fix that by adding some styling.<\/p>\n

      Adding Some Style<\/h3>\n

      To add styles the WordPress way we need to enqueue a stylesheet. The best way to do accomplish this is in two steps.<\/p>\n

        \n
      1. First we register it with WordPress, then, within the widget()<\/code> function we enqueue it. This ensures that WordPress is aware of the existence of our stylesheet but only actually adds it to the page when it is needed.<\/li>\n<\/ol>\n

        To register the stylesheet add the following within the __construct()<\/code> method of our class:<\/p>\n

        Loading gist 895dc034e4da43bf4dc81242ed55f9c4<\/a>

        Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n

          \n
        1. Then, create a widget_styles()<\/code> function within the class. Don’t worry about the name being generic, that’s why it is great to work inside the class, your function names won’t clash with anyone else’s.<\/li>\n<\/ol>\n
          Loading gist 89b221e4b2b26762ca43fdc980fadc24<\/a>

          Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n

          Finally, at the top of the widget()<\/code> function add the following to make sure the stylesheet is added whenever the widget is displayed:<\/p>\n

          Loading gist 21c9f57b8ca893e7c37a1ced71b11497<\/a>

          Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n

          Add any style you like within the stylesheet, it will be applied to your widget. It may be a good idea to wrap your widget in a specific class so you can target it effectively and many before_widget<\/code> code sections will also include your widget’s class.<\/p>\n

          Using The Top Authors Plugin<\/h2>\n
          \n
          \"The
          The Top Authors widget settings.<\/figcaption><\/figure>\n<\/div>\n

          I’m working on a large website rebuild at the moment and one of our key decisions was to either use existing plugins for everything we need, or to code our own general-use plugins if needed. We created a couple of plugins due to this policy.<\/p>\n

          We broke our policy and used\u00a0Top Authors<\/a>\u00a0for two reasons:\u00a0It already existed and its developer Seb Van Dijk<\/a>\u00a0generously donated the plugin to us, which we’ve adopted and taken over. We recoded it a bit, added some new features and released the update to the\u00a0WordPress Plugin Directory.<\/p>\n

          \n\n\n\n
          \"This
          This is what the Top Authors widget looks like on the front-end.<\/figcaption><\/figure>\n\n

          Top Authors went beyond the simple uncustomizable text or text\/Gravatar list. It allowed us to add our own custom template to be used in the widget front-end. We kept this great feature, adding some defaults in the process, and\u00a0extended\u00a0it with a number of hooks.<\/p>\n\n\n\n\n<\/div>\n

          The widget options give you the option to include\/exclude roles, choose which post types to take into consideration and select a display from a preset list, or create your own. We’ve also added an additional ID you can pass to each widget which allows you to use the ta\/post_query<\/code> hook to modify the authors you want to display for each widget.<\/p>\n

          Extending Top Authors<\/h3>\n

          Top Authors already gives you control over the display but you can do a lot more with the hooks, especially the one I mentioned earlier, – ta\/post_query<\/code>. This hook allows you to modify the query that looks up the posts based on which the authors are listed.<\/p>\n

          Let’s back up a bit and figure out how top authors works. Instead of retrieving users directly, we first retrieve posts, and then look at the authors for those posts. The reasoning behind this is that it allows for a much more flexible listing of authors because it allows for the list to be narrowed down based on any criteria.<\/p>\n

          For example, say you want to list your top authors, but only for posts published on weekends that are assigned the featured category. You could restrict the Top Authors widget like this:<\/p>\n

          Loading gist 1de4c4f5151104e03aaf5e8ad09f9d7b<\/a>

          Please update your cookie preferences<\/a> to enable preference cookies to view this gist.<\/p><\/div><\/div>\n

          You can use any parameters that WP_Query<\/a> usually takes since they are passed directly to it. Since the second parameter of the function (the $instance<\/code> variable) contains the widget’s details you can even narrow the use of this function down to a specific single widget using the widget’s id.<\/p>\n

          Conclusion<\/h2>\n

          While there are a bunch of simple author widgets<\/a> around, I didn’t really find any of them to be flexible enough for my own needs. If you need a simple list, a lot of them will do. But if you need something more customizable I think Top Authors is a great choice, or just go full coder and do it yourself!<\/p>\n

          If you have any questions or tips for listing authors let us know in the comments below.<\/strong><\/p>\n","protected":false},"excerpt":{"rendered":"

          For many websites, good authors are their most important asset. Unfortunately, WordPress doesn’t offer an elegant solution for displaying author profiles out-of-the-box. Most of the widgets in the WordPress Plugin Directory are fairly basic, so in this Weekend WordPress Project we show you how to create your own widget.<\/p>\n","protected":false},"author":344049,"featured_media":137545,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"blog_reading_time":"","wds_primary_category":0,"wds_primary_tutorials_categories":0,"footnotes":""},"categories":[263],"tags":[9798],"tutorials_categories":[],"class_list":["post-141266","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-tutorials","tag-weekend-wordpress-projects"],"_links":{"self":[{"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/posts\/141266","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/users\/344049"}],"replies":[{"embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/comments?post=141266"}],"version-history":[{"count":16,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/posts\/141266\/revisions"}],"predecessor-version":[{"id":222807,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/posts\/141266\/revisions\/222807"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/media\/137545"}],"wp:attachment":[{"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/media?parent=141266"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/categories?post=141266"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/tags?post=141266"},{"taxonomy":"tutorials_categories","embeddable":true,"href":"https:\/\/wpmudev.com\/blog\/wp-json\/wp\/v2\/tutorials_categories?post=141266"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}