-
Notifications
You must be signed in to change notification settings - Fork 2
4. Styling the list
Out of the box Recently outputs a very simple HTML list of recent 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. However, this might not be ideal in some cases and so here are a few suggestions you can use as a guide to get the most out of the plugin:
Starting version 3.0, Recently ships with a set of predefined themes that you can apply to your recent posts widget.
To use a theme, head to your WP Dashboard > Appearance > Widgets, expand the Recently 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!
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.
For all of you fellow geeks out there: these themes are Self-Contained Web Components which allows Recently 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.
If you want to make changes to an existing theme (eg. color changes) you have two ways of doing so:
This is the recommended method for most people.
What you need to do:
- Go to your WordPress theme folder (either via FTP or using the file manager provided by your hosting company) and create a folder inside it called
recently. Once created, open therecentlyfolder and create a new one calledthemes. - Go to
/wp-content/plugins/recently/assets/themesand copy the folder of the widget theme that you want to customize (eg.cards). - Go back to your theme's folder, then go to
/recently/themesand paste the widget theme folder here.
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/recently/themes/cards/style.css).
Hook into the recently_additional_theme_styles filter hook to inject your custom CSS rules directly into the theme.
To create a custom theme for the Recently widget you'll need three things:
- A
style.cssfile that contains all of the CSS rules for your custom theme. - A
config.jsonfile that contains the configuration of your theme. - A custom hook to tell Recently where to find your theme.
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:
.recently-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;
}
.recently-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;
}
.recently-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;
}
.recently-my-theme li .item-data .recently-post-title {
display: block;
font-size: 15px;
font-weight: 700;
line-height: 1.3;
}
.recently-my-theme li .item-data a {
color: #eee;
text-decoration: none;
}
.recently-my-theme li .item-data a:hover {
text-decoration: underline;
}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
},
"meta_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>",
"recently-start": "<ul class=\"recently-my-theme\">",
"recently-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 (but feel free to ask any questions if you must.)
The tags seen in the example ({item_position}, {total_items}, and {title}) are called Content Tags. Recently 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 > Recently > Parameters (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.
Now that you have your style.css stylesheet and your config.json file, you need to tell Recently where to find them to make your theme available under the Theme dropdown seen at the end of the Recently widget (Appearance > Widgets > Recently).
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 recently_additional_themes filter hook to tell Recently about your theme folder's location:
/**
* Registers my Recently theme.
*
* @param array $themes
* @return array
*/
function wp861572_register_my_recently_theme($themes){
// Absolute path to the theme folder's location
$themes[] = plugin_dir_path(__FILE__) . 'my-theme'; // Use get_template_directory() instead if your Recently theme is inside a WordPress theme directory.
return $themes;
}
add_filter('recently_additional_themes', 'wp861572_register_my_recently_theme');If everything went well, you should be seeing now your theme being listed under Theme (Appearance > Widgets > Recently). Good job!
If you don't want to use any of the built-in themes or to create a new one, 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:
- Go to Plugins > Editor and select Recently from the dropdown at the right.
- Go to
assets/css/recently.cssto open Recently's stylesheet and copy its contents. - Go to Appearance > Editor and WordPress will automatically open the stylesheet of your current theme for you.
- Paste Recently'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 Recently's CSS rules to your liking and then hit the Update File button to save changes.
- Go to Plugins > Editor and select Recently from the dropdown at the right.
- Go to
assets/css/recently.cssto open Recently's stylesheet. - Tweak the CSS rules to your liking and then hit the Update File button to save changes.
- To preserve changes across plugin updates, move the modified
recently.cssstylesheet 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).