Featured Articles Lite – how to create custom themes

Featured Articles Lite – how to create custom themes

Wednesday, June 1st, 2011 in How to

How to develop themes for Featured Articles LiteAs you may or may not know, Featured Articles Lite is a WordPress plugin that displays slideshows in any page of a WordPress blog. It’s lightweight, fast and has many capabilities, probably the most important being the ability to create new themes for it to truly make it part of the blog displaying it. It already comes with 4 default themes that can be displayed and below I will try to detail as much as possible how to create your own theme.

Please note that some CSS and HTML knowledge is needed in order to complete the task.

1. Folder structure

Each theme developed for Featured Articles Lite is basically a folder containing at least the display file and a stylesheet. The name of the folder can be anything but it must be web safe, meaning it’s best if you use only alpha numeric characters (a-z, 0-9) and underscores.

If, for example, your theme it’s called dark tones, the folder name for the theme would be dark_tones. As mentioned before, the folder must contain at least the display file and a stylesheet. These 2 files must be named display.php (for the slider display file) and stylesheet.css (for the stylesheet file). Below is the complete folder tree of a typical slider theme:

dark_tones (parent folder)

  • display.php
  • stylesheet.css

In addition to the 2 files above, a theme folder can contain, for example, a folder for the images needed by the theme.

2. HTML structure

Main things you need to remember when you create a theme are:

  1. All options you set in admin for a particular slider are stored in variable $options
  2. The width and height (having px or % depending on your choice) of a slider are stored in variable $styles (where x is the width and y is the height)
  3. The database slider id is stored in variable $slider_id (is needed in various places)
  4. A special id needs to be set on the overall container. This is is stored in $FA_slider_id and must be placed or the slider won’t work
  5. The main container must have CSS class FA_slider
  6. Each single article container must have CSS class FA_article
  7. The bottom navigation must have CSS class FA_navigation
  8. The forward navigator must have class FA_next
  9. The back navigator must have class FA_next

All HTML code needed to display the theme is contained inside display.php. First thing you see if you edit a display file from any of the themes that already come with the plugin is this statement:

<?php if ($options['section_display']==1): ?>
	<h2 class="FA_title_section"><?php echo $options['section_title']?></h2>
<?php endif;?>

This condition verifies the option you set from admin section to display or not the title of the slider. All php code needs to be pasted exactly as it is but you can change the h2 CSS class to whatever class you want.

The overall container

Moving on, the next element is the overall container of the slider. Here, there’s a catch when you create your theme. Let’s say the theme is named as above (dark_tones). Because the plugin can display multiple sliders on a single page and each slider can have a different theme, you need to somehow make you theme be unique. To do that, make sure you use a unique CSS class among all themes you already have in FA Lite. Best would be to name it FA_overall_container_dark_tones (in your theme you will replace dark_tones with the name of your theme) and in your stylesheet make all children elements of this overall container descend from this element (ie. .FA_overall_container_dark_tones #my_inner_element{styling in here}).

Next, in order to be able to start the slider, this element must have a second CSS class named FA_slider. You need to do this because the JavaScript that runs the slider uses as selector this exact CSS class so if you forget to set this as a second class the slider won’t work because the script doesn’t know about it.

The next thing you need to set on this element is the width. As you may already have noticed, in admin you have the possibility to manually set the width and height of the slider so you can make it the exact size you want. This element only controls the width so you need to set that. To do this, you need to add:

 style="<?php echo $styles['x'];?>"

And last, you need to set the slider ID that is provided by the back-end php and stored into variable $FA_slider_id. In the end you should have something looking like this in your page:

<?php if ($options['section_display']==1): ?>
	<h2 class="FA_title_section"><?php echo $options['section_title']?></h2>
<?php endif;?>
<div class="FA_overall_container_dark_tones FA_slider" style="<?php echo $styles['x'];?>" id="<?php echo $FA_slider_id;?>">

</div>

The articles container

All articles displayed into the slider are placed inside a second container inside the overall container. The CSS class of this element can be anything, it’s not used as a selector so you can put whatever class name you want on it in order to style it. One thing to remember is the fact that this element is the one that controls the height of the slider so we need to set the height for it similar to the way we did with the previous element:

style="<?php echo $styles['y'];?>"

By now, your display.php file should look like this:

<?php if ($options['section_display']==1): ?>
	<h2 class="FA_title_section"><?php echo $options['section_title']?></h2>
<?php endif;?>
<div class="FA_overall_container_dark_tones FA_slider" style="<?php echo $styles['x'];?>" id="<?php echo $FA_slider_id;?>">
	<div class="FA_featured_articles" style="<?php echo $styles['y'];?>">

	</div>
</div>

The articles

The plugin passes to the theme all selected posts according to your admin setting into an array called $postlist. In order to display the posts, you need to loop this array something like this:

<?php foreach ($postslist as $post):?>

<?php endforeach;?>

Inside that loop, the details about the post are stored in variable $post so we can access them from there. Now let’s start constructing the HTML to display the posts. In order for the JavaScript slider to know what element to slide, the container of all post details must have class FA_article. Again, this class is used as selector to determine what elements to apply effects on.

<?php foreach ($postslist as $post):?>
	<div class="FA_article">
	</div>
<?php endforeach;?>

Next, inside FA_article there’s another wrapper div element. This is needed because of the padding. If we set padding directly on .FA_article (it has 100% width), the element will be too big and part of it won’t be visible. So it’s easier to add another element inside it and set the padding on it so that the text and image won’t start right from the edge.

<?php foreach ($postslist as $post):?>
	<div class="FA_article">
		<div class="FA_wrap">

		</div>
	</div>
<?php endforeach;?>

Finally, we start displaying information. First thing is the post image. The plugin provides a function that automatically detects the post image so let’s use it:

<?php if( $image = FA_article_image($post, $slider_id) ):?>			

<?php endif;?>

A little note about this function (FA_article_image). In versions previous to 2.3, this function only had a single argument (since only one slider existed). Starting with version 2.3, this function has 2 arguments, the post and the Featured Articles slider id (stored in variable $slider_id). This is needed because 2 different sliders can have different thumbnail sizes and the plugin must ask WordPress for the size you entered in administration area.

Moving on, we start displaying the image (if the condition returned an image path)

<?php if( $image = FA_article_image($post, $slider_id) ):?>			
   <div class="image_container"><img src="<?php echo $image;?>" alt="<?php the_title('','');?>" class="FA_image" /></div>
<?php endif;?>

The image container and the image itself can have any CSS class you want to set for it. You can even drop the container div and display the image directly. It all depends on how you want to structure your display.

By now, the display file should look something like this:

<?php if ($options['section_display']==1): ?>
	<h2 class="FA_title_section"><?php echo $options['section_title']?></h2>
<?php endif;?>
<div class="FA_overall_container_dark_tones FA_slider" style="<?php echo $styles['x'];?>" id="<?php echo $FA_slider_id;?>">	
	<div class="FA_featured_articles" style="<?php echo $styles['y'];?>">
	<?php foreach ($postslist as $post):?>
		<div class="FA_article">	
			<div class="FA_wrap">
				<?php if( $image = FA_article_image($post, $slider_id) ):?>			
                    <div class="image_container"><img src="<?php echo $image;?>" alt="<?php the_title('','');?>" class="FA_image" /></div>
                <?php endif;?>                	
	<?php endforeach;?>			
	</div>		
</div>

After the image is displayed, we start showing the post title, the date of the article, the description and the read more link. These are the last elements that are displayed into the slider for a certain article by the default themes. In your custom theme you can display additional information (the_category(), comments_number() …) by using some of WordPress’s template tags but the default themes display only this information.

Let’s start with the title:

<?php if( $options['title_click'] ):?>
    <a href="<?php the_permalink();?>" title="<?php the_title();?>">
<?php endif;?>
    <?php the_title();?>
<?php if( $options['title_click'] ):?>
    </a>
<?php endif;?>
</h2>

As you may have observed, there’s also a verification made to check if the title is a link or simply text. The verification is made against the administration setting you set for a particular slider.

Next is the post date:

<span class="FA_date"><?php the_time(get_option('date_format')); ?></span>

The post description is stripped of any HTML tags except the one you set in slider settings and truncated to the number of characters set in admin by using the FA_truncate_text function. The srtipped contents of the post are stored in $post->FA_post_content.

<p><?php echo FA_truncate_text($post->FA_post_content, $image ? $options['desc_truncate'] : $options['desc_truncate_noimg']);?></p>

And last, the read more link for a particular post:

<a class="FA_read_more" href="<?php the_permalink();?>" title="<?php the_title();?>"><?php echo $options['read_more'];?></a>

This is it, posts are displayed, all is in place. What is left to do is set up the navigation and we’ll be good to go. But before that, let’s see the complete code so far:

<?php if ($options['section_display']==1): ?><h2 class="FA_title_section"><?php echo $options['section_title']?></h2><?php endif;?>
<div class="FA_overall_container_dark_tones FA_slider" style="<?php echo $styles['x'];?>" id="<?php echo $FA_slider_id;?>">	
	<div class="FA_featured_articles" style="<?php echo $styles['y'];?>">
	<?php foreach ($postslist as $post):?>
		<div class="FA_article">	
			<div class="FA_wrap">
				<?php if( $image = FA_article_image($post, $slider_id) ):?>			
                    <div class="image_container"><img src="<?php echo $image;?>" alt="<?php the_title('','');?>" class="FA_image" /></div>
                <?php endif;?>
                <h2>
				<?php if( $options['title_click'] ):?>
                	<a href="<?php the_permalink();?>" title="<?php the_title();?>">
				<?php endif;?>
					<?php the_title();?>
				<?php if( $options['title_click'] ):?>
                	</a>
				<?php endif;?>
                </h2>
                
                <span class="FA_date"><?php the_time(get_option('date_format')); ?></span>
                <p><?php echo FA_truncate_text($post->FA_post_content, $image ? $options['desc_truncate'] : $options['desc_truncate_noimg']);?></p>	
                <a class="FA_read_more" href="<?php the_permalink();?>" title="<?php the_title();?>"><?php echo $options['read_more'];?></a>
			</div>			
		</div>	
	<?php endforeach;?>			
	</div>	
</div>

The bottom navigation

First thing to set up for the bottom navigation is to check if it’s enabled from administration. Also, another good check would be to see if there are more than one post into the slider because if there’s only one post, there’s no point in displaying the bottom navigation.

<?php if( $options['bottom_nav'] && count($postslist) > 1 ):?>

<?php endif;?>

As mentioned above, the bottom navigation must have CSS class FA_navigation set on it because, you guessed, it’s used as selector by the slider script. In all themes I used unordered list to display it so here goes:

<?php if( $options['bottom_nav'] && count($postslist) > 1 ):?>
	<ul class="FA_navigation">
	
	</ul>
<?php endif;?>

Now, inside that list we start a loop on $postlist to display the exact number of list elements as the number of posts:

<?php if( $options['bottom_nav'] && count($postslist) > 1 ):?>
	<ul class="FA_navigation">
		<?php foreach ($postslist as $k=>$post):?>
			<li<?php if($k==0):?> class="first"<?php endif;?>>
				<span class="FA_current"><?php the_title();?></span>
				<a href="#" title=""></a>
			</li>
		<?php endforeach;?>	
	</ul>
<?php endif;?>

This should be it. The only thing to note is that inside each li you must have both span.FA_current and the empty anchor.

The sideways navigation

Last thing to do is the sideways navigation. Again, just like we did with the bottom navigation, we check to see if it must be displayed:

<?php if( $options['sideways_nav'] && count($postslist) > 1 ):?>

<?php endif;?>

Next, create the 2 links for back and forward navigation. Remember, these links must have CSS class FA_back (for back link) and FA_next for next link.

<?php if( $options['sideways_nav'] && count($postslist) > 1 ):?>
	<a href="#" title="<?php __('Previous post');?>" class="FA_back"></a>
	<a href="#" title="<?php __('Next post');?>" class="FA_next"></a>
<?php endif;?>

Last thing you should remember is that everything (all articles and both navigations) must be contained inside the overall container.

Was this useful? Show your support.

digg Featured Articles Lite – how to create custom themes

42 comments

  1. finid says:

    Excellent guide.

    I am attempting to deploy the slider on my site, but I observe that when the page starts to load, the contents of the slider are collapsed, so the page looks really terrible.

    Is there way to load the slider with the contents intact?

    • Thank you, I tried to detail as much as possible. Glad to hear you find it useful. About your problem, this happens because styles load in footer. One thing you could do is to either hide the whole thing (in your main stylesheet put .FA_slider{display:none} ) and inside the stylesheet of the theme you’re using add .FA_slider{display:block;}

      Not the most elegant solution but I really am out of ideas on how to solve this issue.

      One other solution would be to put the contents of the stylesheet you’re using directly inside your main stylesheet. Again, not the best option because 1. you probably won’t display the slider in all your pages and 2. you’ll have to do this every time the theme changes.

      I’ll try and think of a better way to deal with this.

  2. finid says:

    Thanks for the prompt reply. I’ll try your suggestion later today and report on it.

    Note that this is not an issue if the slider is below the scroll because by the time the whole page loads, the slider is already fully loaded, and, therefore, the issue I described is not visible to the visitor.

  3. finid says:

    About images, in my testing, images in the posts did not load.

    Do I need to specify a post while creating a post, or is the slider supposed to grab the first image in a post and re-size it?

  4. finid says:

    No luck. The hack did not work.

    Btw, I think that should be .FA_display_slider, not .FA_slider

  5. finid says:

    Ok, I made some progress, and I think I can run with it – temporarily.

    In the plugin’s css file, there is the .FA_overall_container_light selector, with a display:block declaration.

    I copied that selector to my theme’s css file and gave it a display:none declaration.

    I also made a few other style changes to make it look pretty. You may view the result at http://linuxbsdos.com/ask

    This is temporary because where I want to use it is on the main site. The other issue I’ll like to understand is how the thumbnails are supposed to be pulled in. When I tested it on the main site, thumbnails were not displayed. Do I need to regenerate the thumbnails or how is that supposed to work?

    What’s you take on the thumbnails?

  6. finid says:

    With the changes I made came a few issues.

    1. Watch the bottom navigator as it cycles through the list of items. Did you observe anything at the first item as it cycles to the last item.

    2. Author link is dislodged, so that it displays outside of the box. Does not look very good. That is why I disabled it in the admin page.

  7. finid says:

    I now have it on the main site. See it on any single page view of http://linuxbsdos.com

  8. finid says:

    On the main site, http://linuxbsdos.com, click on any article. It’s right at the top of every single post page.

    • Aha, couldn’t know that and you can imagine I can’t browse the entire site just to find where the plugin is displayed. Now:

      1. The bottom navigator isn’t actually that, it’s the read more link that is empty, it doesn’t have any text in it. Go to settings and make sure you enter some text into read more field.
      2. The author link is not aligned with the slider because the slider has right/left margin as auto. To center the author link, put in styles/fa_dev.css line line 1 margin:0px auto;

      If I may make a suggestion. I see you changed directly into light theme. Make a copy of that, call it custom_light and use that one. This way, if an update that needs to change something in themes will be released, your theme will remain intact and you’ll be able to update it with the possible changes.

  9. finid says:

    I want the author link to be in the original position, where it is hidden until a mouseover the i. I’ll tweak it further to see if I can get it in the original position.

    It is true that the light theme was modified. This is just a test for me. I will create a custom theme before applying any updates.

    On the thumbnails, what’s your thought on that? Why are they not showing in the slider?

  10. finid says:

    I see you’ve just updated the plugin. Thank you.

    Still on images, if I specify a custom image, the plugin is not using the thumbnail size specified in WP. The displayed thumbnail is about twice the specified size, and the height is more than the specified maximum in FA Lite’s admin options.

    I can see that one of the bugs fixed in the update relates to images, but I don’t think it relates to what I just described.

    • Here’s how things work regarding images. When you set an image on a post using the plugin’s meta box, it won’t set any particular size, only the image id. When the slider gets displayed, it will display the image by asking wordpress for the size you entered in slider settings for that particular slider. So if, let’s say, you enter 250 x 250 on slider settings for thumbnail size, the plugin will use wp_get_attachment_image_src() and ask for the most appropriate size. What image gets returned depends entirely on WordPress.

      Things go similar for image detected in post content. The plugin tries to identify the image id and if that’s successful, it will set that image id on the post so it won’t have to do the scan again.

      One thing you could do is to create images having exact size you want to display into the slider and place them as custom FA Lite image on posts/pages and use the same size on the thumbnail size settings for that particular slider.

  11. finid says:

    I set the thumbnail size in WP the same as the maximum dimensions of thumbnails in the slider settings – 150×150, but the displayed image does not match this. Do you think it’s necessary to regenerate thumbnails for older posts?

    I could use the suggestion you made, but I’m trying to make use, if possible, of an automated approach.

    • If the 150×150 image isn’t available to wordpress, it will return the next best matching image. If your images are old and you uploaded them with previous WP versions (and I assume you did), re-uploading them and setting the 150×150 thumbnail size in wp settings should help.

  12. finid says:

    Thanks.

    Thinking about it again, I think the image used by the automated approach might not be the one I want displayed for a post, so I think the manual will be better. That will ensure that the image displayed will be the one of my chosen, and not the first image in the post.

  13. finid says:

    The size of the thumbnail returned by wp depends on the size of the image regardless of the thumbnail size specified in wp’s media settings. In other words, it is not fixed.

    And FA Lite does not seem to be able to enforce the maximum thumbnail size specified in its settings page. That’s why you see in the slider on my site a significant diff between the two thumbnails showing. I think the way that is to find out the size of the image that returns the right thumbnial and use that size for all featured images.

    few suggestions:

    1. It would be nice to be able to have the slider show related posts in the same category as the post being read, that is, automatically.

    2. If the option to make the post titles clickable is enabled, I think the “read more” feature should be disabled, as it does not seem to be necessary. At least you could also make it optional, just like the clickable titles.

  14. Jen says:

    Hi Constantine! I LOVE this plugin! It is incredible!!! I hate to ask, but if you get a moment, could you tell me how to remove the dates when I select ‘pages’ rather than ‘posts’ to display? I can’t seem to find a setting or the coding for it. (I’m doing this project for a non-profit even though I’m not a web designer by trade!) Thanks so much for any assistance. I appreciate the plugin with or without this extra bit!

    • You’ll have to do some manual editing. In order to hide date from pages display, you need to edit display.php file of the theme(s) you using and add a condition.
      The part displaying the date looks something like this:


      <span class="FA_date"><?php the_time(get_option('date_format')); ?></span>

      In order to hide it for pages, the above should look something like this:

      <?php if( $post->post_type != 'page' ):?>
      <span class="FA_date"><?php the_time(get_option('date_format')); ?></span>
      <?php endif;?>

      This should do it. Let me know if it works.

  15. Jen says:

    Sorry- Just realized I added an extra ‘e’ to your name.

  16. Paul B says:

    Hi

    Is there anyway that I can get the plugin to display the post excerpt rather than the post itself? I am linking to a post with media inserted and the media shortcode stuff is showing in the description.

    So I am getting stuff like this: [hana-flv-player video='http://localhost/site/wp-content/uploads/2011/05/Filename.flv' /] 4 licks from Doug

  17. Andy says:

    Displays great in Firefox & Chrome (of course) but I can’t seem to get rid of the horrid jagged fonts in IE8 (presumably the same in IE7/9 also). I seem to recall finding an answer for another plugin that had the same problem a couple of years back – any ideas?
    Thanks, Andy

    • This happens on IE when you animate opacity (like this plugin does). One solution would be to put background color on the element, in our case I guess it’s the title that displays badly. Just put a background color on titles from theme CSS and it should work.

  18. Andy says:

    Would it not be possible to apply the fix the plugin? Post titles already have a background colour applied in my theme.

    • Yes, it will be possible. I missed this for so many times because it’s a small fix and I almost always (I remember about it when people ask about this problem you have) forget about it. Sorry about this, in my defense, I’m only human :)

  19. Andy says:

    Hey, no problem just whenever you can update the plugin is fine. We appreciate the work you clever developers do! I’ll keep an eye out for an update. Thanks, Andy

  20. Razvan says:

    How do you change the fonts in the slider ? I’m not very familiar with the css structure.

  21. Andy says:

    Hi again – the IE font display problem again.
    Would you be able to tell me where in the scripts I could place some code (and wht the code would be) to fix the jagged font issue in IE7/8? All other browsers display fine (of course) but as a high percentage of site visitors are still using these browsers, I’ll have to fix this or be forced to change to another method of showing featured posts – which I don’t want to do as I really like using the plugin.
    If you can point me in the right direction, it would be very much appreciated.
    Thanks again, Andy

    • I don’t know who I already told this but made the change permanent in themes and with the next update this will get fixed. Anyway, till that’s released, a fix for this would be to put a background color in theme stylesheet for h2 elements. The background color for the theme you’re using is #EAEAEA. In your theme stylesheet locate this declaration: .FA_overall_container_light .FA_featured_articles .FA_article h2 and add

      background-color:#EAEAEA;

      That should do it.

  22. Andy says:

    Thanks Constantin, tried that and managed to get the article heading much clearer. The article font still is a little fuzzy even though I added the same background colour to that font style. But overall, I’m very happy with the end result, so many thanks again for taking the time to answer my questions!

  23. [...] Themes – 4 default themes unfilled for your featured posts; undemanding implementation for new themes (a detailed handbook on making themes can be found here) [...]

  24. Thanks for the plugin, Constantin. It’s really awesome. One thing that initially intimidated me was the rather complex styling structure – i.e. at least a separate PHP and CSS file for each theme – until I realized that changing CSS a little bit, e.g. changing the font-family values, is as simple as copying a theme folder with its contents and give that folder a different name, then tweak the CSS. In that simple case there’s no need at all to tinker with the PHP file, or even the names of IDs or classes… So it turned out incredibly easy to adjust to “my” case. And: the slide effect is really classy. It’s a wonderful plugin, thanks again!

    • I forgot a suggestion: allow placing custom theme folders somewhere outside the plugins folder, as upgrades tend to destroy the content of the upgraded plugin’s folder. Often the /wp-content/uploads/ or the /wp-content/ folder is used by other plugins for that.

      • Brilliant man, thank you very much for the suggestion. Don’t know if you know it yet but we’ll be releasing an update soon (2-3 more weeks from now) and this will definitely get implemented. Again, thanks for the suggestion and for stopping to say you like it, means a lot for me.

  25. Cburke says:

    Great slider, however there is a bug in IE in which the .FA_article class is still displayed on the page even when you have faded to the next slide. You are only changing the opacity of the div, you also need to change the display to none. This can be seen if you mouse over a link title that is underneath the current article, its alt text can be seen and the link is still clickable. I was able to get around this by editing the JQuery plugin featuredArticles.jquery.js by adding diplay:none and display:block accordingly:

    switch (fading) {
    case “top”:
    $(this.slides[this.currentKey]).css({‘top’:0,’z-index’:1,’display’:'none’}).animate({
    opacity: 0,
    top: dir * o.fadeDist
    },{queue:false, duration:o.effectDuration});
    $(this.slides[index]).css({‘top’: -dir*o.fadeDist, ‘z-index’:100,’display’:'block’}).animate({
    opacity: 1,
    top: 0,
    },{queue:false, duration:o.effectDuration});
    break;
    case “left”:
    $(this.slides[this.currentKey]).css({‘left’:0, ‘z-index’:1,’display’:'none’}).animate({
    opacity: 0,
    left: dir * o.fadeDist,
    },{queue:false, duration:o.effectDuration});
    $(this.slides[index]).css({‘left’:-dir*o.fadeDist, ‘z-index’:100,’display’:'block’}).animate({
    opacity: 1,
    left: 0,
    },{queue:false, duration:o.effectDuration});
    break
    }

    Hopefully you include this fix in any futures updates because this is a really great plugin. Thanks for the great slider!!!!

  26. Mandea says:

    What about touch device support?
    on iPhone, now you need to “double click” on the bottom navigation button to change slides.
    Thank you

Leave a comment