Skip to content

6. Styling the list

Jump to bottom
Héctor Cabrera edited this page Jun 8, 2024 · 52 revisions

Out of the box WordPress Popular Posts outputs a very simple HTML list of popular posts with basically no predefined design. The list uses the styles provided by your current WordPress theme which maximizes the chances of a better integration with its look & feel.

If you want your popular posts list to have a more elaborate design WPP provides two different ways to customize it:

Themes

Starting version 5.0, WordPress Popular Posts ships with a set of predefined themes that you can apply to your popular posts block/widget ("widget themes" from now on).

To use a theme, head to your WP Dashboard > Appearance > Widgets, expand the WordPress Popular Posts widget to access its options, and under Theme you'll find a list of available themes. Choose one, change stuff around if you need to (options, HTML tags, etc.), then hit Save to apply it. You're done!

If you're using the WordPress Popular Posts block scroll down to its Theme section, pick the theme you want to use, preview it and/or customize it if you want to, and save changes. That's it!

Note that if you're using a plugin that aggregates inline CSS (eg. Autoptimize) you'll need to disable such feature as themes will break with it enabled.

Browser Support

For all of you fellow geeks out there: these themes are Self-Contained Web Components which allows WordPress Popular Posts to style the widget in a way that it won't affect other components on the webpage and, more importantly, the widget themes themselves won't be affected by global CSS rules either. Note that this is true for all web browsers that support the Shadow DOM: Google Chrome, Mozilla Firefox, Safari, Opera, Microsoft Edge, etc.

The above doesn't mean that themes won't work at all on browsers that don't support the Shadow DOM. There's a good chance that the themes will still work, however expect some visual artifacts and/or (minor) issues.

Customizing an existing theme

If you want to make changes to an existing widget theme (eg. color changes) you have two ways of doing so:

Copy the widget theme folder into your WordPress theme (available since version 5.3.0)

This is the recommended method for most people.

What you need to do:

  1. Create a wordpress-popular-posts folder inside your WordPress theme (eg. /wp-content/themes/twentytwentyone/wordpress-popular-posts/). Open the newly created wordpress-popular-posts folder and create another one inside called themes (eg. /wp-content/themes/twentytwentyone/wordpress-popular-posts/themes/).
  2. Next, go to /wp-content/plugins/wordpress-popular-posts/assets/themes/ and copy the folder of the widget theme that you want to modify (eg. cards).
  3. Go back to /wp-content/themes/[YOUR-THEME]/wordpress-popular-posts/themes/ and paste the widget theme folder that you previously copied here (eg. /wp-content/themes/twentytwentyone/wordpress-popular-posts/themes/cards/).

When you're done you can make changes to the widget theme (change link colors, use a different font size for headings, etc.) by modifying its stylesheet (eg. /wp-content/themes/twentytwentyone/wordpress-popular-posts/themes/cards/style.css).

Use a custom hook to add your CSS rules to the theme

Hook into the wpp_additional_theme_styles filter hook to inject your custom CSS rules directly into the theme.

Developing a custom theme

To create a custom theme for the WordPress Popular Posts widget you'll need three things:

  1. A style.css file that contains all of the CSS rules for your custom theme.
  2. A config.json file that contains the configuration of your theme.
  3. A custom hook to tell WordPress Popular Posts where to find your theme.

1. style.css

Nothing much to say here. Just add your custom CSS rules here and make sure to name your stylesheet as style.css.

Here's an example:

.wpp-my-theme {
    counter-reset: wpp-counter;
    margin-left: 0;
    margin-right: 0;
    padding: 0;
    border-right: 6px solid rgb(210, 105, 30);
    box-sizing: border-box;
}

    .wpp-my-theme li {
        position: relative;
        display: flex;
        align-items: center;
        counter-increment: wpp-counter;
        position: relative;
        list-style: none;
        margin: 0;
        padding: 15px 15px 15px 0;
        background: rgba(210, 105, 30, calc((((var(--total-items) - (var(--item-position) - 1)) * 100)/var(--total-items))/100));
        box-sizing: border-box;
    }

        .wpp-my-theme li .item-position::before {
            display: inline-block;
            flex: 1 0 0;
            content: counter(wpp-counter);
            color: rgba(255, 255, 255, 0.3);
            width: 40px;
            font-size: 18px;
            font-weight: 700;
            letter-spacing: -1px;
            text-align: center;
        }

            .wpp-my-theme li .item-data .wpp-post-title {
                display: block;
                font-size: 15px;
                font-weight: 700;
                line-height: 1.3;
            }

            .wpp-my-theme li .item-data a {
                color: #eee;
                text-decoration: none;
            }

            .wpp-my-theme li .item-data a:hover {
                text-decoration: underline;
            }

2. config.json

The config.json file holds information about your theme: who made it, what settings to apply, etc. Here's an example:

{
    "name": "My Theme Name",
    "description": "My Theme Description",
    "authors": [
        {
            "name": "John Doe",
            "email": "john-doe@example.com"
        }
    ],
    "config": {
        "shorten_title": {
            "active": false,
            "length": 25,
            "words": false
        },
        "post-excerpt": {
            "active": false,
            "length": 75
        },
        "thumbnail": {
            "active": false,
            "width": 75,
            "height": 75
        },
        "stats_tag": {
            "comment_count": false,
            "views": false,
            "author": false,
            "date": {
                "active": false,
                "format": "F j, Y"
            },
            "taxonomy": {
                "active": false,
                "name": "category"
            }
        },
        "markup": {
            "title-start": "<h2>",
            "title-end": "</h2>",
            "wpp-start": "<ul class=\"wpp-my-theme\">",
            "wpp-end": "</ul>",
            "post-html": "<li style=\"--item-position: {item_position}; --total-items: {total_items};\"><div class=\"item-position\"></div> <div class=\"item-data\">{title}</div></li>"
        }
    }
}

Most of the fields are pretty self-explanatory. The ones under config are pretty much the exact same parameters as the ones seen in Settings > WordPress Popular Posts > Parameters.

The tags seen in the example ({item_position}, {total_items}, and {title}) are called Content Tags. WordPress Popular Posts will replace these with actual data from your site when rendering the list to the screen. You can find a complete list of Content Tags via Settings > WordPress Popular Posts > Parameters, under post_html (you can add your own Custom Content Tags too!)

A tip: use JSONLint to check for errors in your config.json file. Make sure it's valid before proceeding onto the next step.

3. Telling WordPress Popular Posts where your theme is

Now that you have your style.css stylesheet and your config.json file, you need to tell WordPress Popular Posts where to find them to make your theme available under the Theme dropdown seen at the end of the WPP widget (Appearance > Widgets > WordPress Popular Posts).

To do so create a folder (eg. my-theme) either in your theme's directory or in a custom plugin, place your style.css and your config.json files in it, then hook into the wpp_additional_themes filter hook to tell WordPress Popular Posts about your theme folder's location:

/**
 * Registers my WPP theme.
 *
 * @param   array   $themes
 * @return  array
 */
function wp861572_register_my_wpp_theme($themes){
    // Absolute path to the theme folder's location
    $themes[] = plugin_dir_path(__FILE__) . 'my-theme'; // Use get_template_directory() instead if your WPP theme is inside a WordPress theme directory.

    return $themes;
}
add_filter('wpp_additional_themes', 'wp861572_register_my_wpp_theme');

If everything went well, you should be seeing now your theme being listed under Theme (Appearance > Widgets > WordPress Popular Posts). Good job!

Themeing the popular posts list the "regular" way

If you don't want to use any of the built-in themes you can still style your popular posts list the traditional way via CSS. To do so, you'll need to do either of the following:

Import WPP's CSS classes into your theme's stylesheet, and tweak it from there

  1. Go to Plugins > Editor and select WordPress Popular Posts from the dropdown at the right.
  2. Go to assets/css/wpp.css to open WPP's stylesheet and copy its contents.
  3. Go to Appearance > Editor and WordPress will automatically open the stylesheet of your current theme for you.
  4. Paste WPP's CSS rules at the end of the file (be very careful not to overwrite / delete any preexisting CSS rules you find in there or else a world of pain might come your way!), tweak WPP's CSS rules to your liking and then hit the Update File button to save changes.

Tweak WPP's stylesheet directly

  1. Go to Plugins > Editor and select WordPress Popular Posts from the dropdown at the right.
  2. Go to assets/css/wpp.css to open WPP's stylesheet.
  3. Tweak the CSS rules to your liking and then hit the Update File button to save changes.
  4. To preserve changes across plugin updates, move the modified wpp.css stylesheet into your theme's directory (if you don't know how, you should probably stick to the first option or ask your developer to do this for you).

Here are a few examples on what can be done with a little CSS, time and imagination :P

Examples

Some of these layouts were tested under the Twenty Thirteen theme. You'll probably need to make some adjustments to the CSS styles below to make them work on your theme.

Card Style

Card style

Instructions:

Add this CSS code to your theme's stylesheet (located at wp-content/YOUR-THEME-FOLDER/style.css):

.wpp-list {
}

    .wpp-list li {
        overflow: hidden;
        margin: 0 0 1em 0;
        padding: 1em 0 1em 0;
        border-bottom: #ddd 1px solid;
    }

    .wpp-list li:first-of-type {
        padding: 0 0 1em 0;
    }

        .wpp-list li .wpp-thumbnail {
            float: left;
            margin: 0 1em 0.6em 0;
        }

        .wpp-list li .category,
        .wpp-list li .wpp-post-title {
            display: block;
            font-weight: bold;
        }

        .wpp-list li .category {
            margin-bottom: 0.6em;
            color: #0366d6;
            font-size: 0.8em;
            line-height: 1;
        }

        .wpp-list li .wpp-post-title {
            margin-bottom: 0.2em;
            font-size: 1.1em;
            line-height: 1.3;
        }

        .wpp-list li .wpp-excerpt {
            float: none;
            clear: both;
            margin: 0;
        }

Go to Appearance > Widgets, then click on the WordPress Popular Posts widget on your sidebar to access its settings.

Under Posts settings, tick the Display post excerpt checkbox.

Under Stats Tag settings, tick the Display taxonomy checkbox.

Under HTML Markup settings, tick the Custom HTML markup checkbox and Save.

Set Post HTML Markup to <li>{thumb} {category} {title} <p class="wpp-excerpt">{excerpt}</p></li>.

Save changes.

CSS3 Ordered list #1

Ordered list

Credits: José Vargas, at codeitdown.com

Instructions:

First, add this to the end of your theme's stylesheet (located at wp-content/YOUR-THEME-FOLDER/style.css):

ol.wpp-list {
    list-style-type: none;
    margin: 0 0 0 3em;
    padding: 0;
    counter-reset: li-counter;
}

ol.wpp-list > li{
    position: relative;
    margin-bottom: 20px;
    padding-left: 0.5em;
    min-height: 3em;
    border-left: 2px solid #CCCCCC;
}

ol.wpp-list > li:before {
    position: absolute;
    top: 0;
    left: -1em;
    width: 0.8em;
    font-size: 3em;
    line-height: 1;
    font-weight: bold;
    text-align: right;
    color: #464646;
    content: counter(li-counter);
    counter-increment: li-counter;
}

ol.wpp-list li span.wpp-stats { display:block; }

Go to Appearance > Widgets, then click on the WordPress Popular Posts widget on your sidebar to access its settings.

Under Posts settings, tick the Display comment count and Display views checkboxes.

Under HTML Markup settings, tick the Custom HTML markup checkbox and Save.

Set Before / after Popular Posts to <ol class="wpp-list"> and </ol>, respectively.

Set Post HTML Markup to <li>{thumb} {title} <span class="wpp-stats">{stats}</span></li>.

Save changes.

CSS3 Ordered List #2

Ordered list

Credits: Robert Johansson at 456 Berea Street.

First, add this to the end of your theme's stylesheet (located at wp-content/YOUR-THEME-FOLDER/style.css):

ol.wpp-list {
    counter-reset: li; /* Initiate a counter */
    margin-left: 0; /* Remove the default left margin */
    padding-left: 0; /* Remove the default left padding */
}

ol.wpp-list > li {
    position: relative; /* Create a positioning context */
    margin: 0 0 6px 2em; /* Give each list item a left margin to make room for the numbers */
    padding: 4px 8px; /* Add some spacing around the content */
    list-style: none; /* Disable the normal item numbering */
    border-top: 2px solid #666;
    background: #31191c;
}

ol.wpp-list > li:before {
    content: counter(li); /* Use the counter as content */
    counter-increment: li; /* Increment the counter by 1 */
    /* Position and style the number */
    position: absolute;
    top: -2px;
    left: -2em;
    -webkit-box-sizing: border-box;
    box-sizing: border-box;
    width: 2em;
    /* Some space between the number and the content in browsers that support
       generated content but not positioning it (Camino 2 is one example) */
    margin-right: 8px;
    padding: 4px;
    border-top: 2px solid #666;
    color: #fff;
    background: #666;
    font-weight: bold;
    font-family: "Helvetica Neue", Arial, sans-serif;
    text-align: center;
}

Go to Appearance > Widgets, then click on the WordPress Popular Posts widget on your sidebar to access its settings.

Under Posts settings, untick the Display comment count and Display views checkboxes.

Under HTML Markup settings, tick the Custom HTML markup checkbox and Save.

Set Before / after Popular Posts to <ol class="wpp-list"> and </ol>, respectively.

Set Post HTML Markup to <li>{title}</li>.

Save changes.

CSS3 Ordered List #3

Ordered list

Credits: Alexios Tsiaparas at Stack Overflow

First, add this to the end of your theme's stylesheet (located at wp-content/YOUR-THEME-FOLDER/style.css):

ol.wpp-list {
	margin-left: 0;
	padding-left: 0;
	counter-reset: item;
}
ol.wpp-list > li {
	margin-left: 0;
	padding-left: 0;
	counter-increment: item;
	list-style: none inside;
	margin-bottom: 5px;
}

ol.wpp-list > li:before {
	content: counter(item);
	padding: 3px 10px;
	margin-right: 0.5em;
	background: #381d20;
	-webkit-border-radius: 10px;
	-moz-border-radius: 10px;
	border-radius: 10px; 
}

ol.wpp-list li span.wpp-stats {
	display: block;
	margin-left: 2.7em;
}

Go to Appearance > Widgets, then click on the WordPress Popular Posts widget on your sidebar to access its settings.

Under Posts settings, tick the Display comment count and Display views checkboxes.

Under HTML Markup settings, tick the Custom HTML markup checkbox and Save.

Set Before / after Popular Posts to <ol class="wpp-list"> and </ol>, respectively.

Set Post HTML Markup to <li>{thumb} {title} <span class="wpp-stats">{stats}</span></li>.

Save changes.

See also

Clone this wiki locally