Creating a Theme

What do I need to know?

A Post Highlights Theme is basically a WordPress Loop. So if you are familiar with customizing your WordPress Loop, it will be really easy for you. Here is what you need:

  • Basic HTM knowledge
  • Know the WordPress Template Tags
  • CSS styling

Overview

A Post Highlights theme is a folder under the themes directory in post-highlights. The only required file to be under this folder is “index.php”, but there are several optional others you may want to add:

  • post-highlights
    • themes
      • default
      • yourtheme
        • index.php – main file
        • style.css – the stylesheet for your theme
        • settings.php – a file to register your theme settings
        • script.js – override the default post highlights JS with your own
        • image files that may be part of your theme

Step by step

Create a folder with the required files

At this step, we recommend you to duplicate the default theme folder. It has comments all over the code that will help you through the process.

Understanding the index.php file

index.php is composed of two parts: a Loop, and optional navigation elements. Lets start with the Loop:

The Loop

The loop in the index.php of a post highlight theme is very similar to the very well know WordPress Loop. In fact, you can use any of WordPress Template Tags here. Letss see its basic structure:

1. First, lets check if there is any post to display and then start the loop:

1
2

<?php if ($highlightedPosts->have_posts()) : ?>
<?php while ($highlightedPosts->have_posts()) : $highlightedPosts->the_post(); ?>

$highlightedPosts is initialized by Post highlights, so you must use this name.

2. From now on it will look just like any other WordPress Loop. First thing we want to do is to retrieve the information about the picture and the headline to use:

1
2
3
4

<?php
$headline = get_post_meta(get_the_ID(), 'ph_headline', true);
$imageurl = get_post_meta(get_the_ID(), 'ph_picture_url', true);
?>

3. Now we open the div that will wrap each highlighted post:

1

<div id="ph_highlight-<?php echo $counter; ?>" class="ph_post">

This DIV will allways be there. It MUST have the ph_post class and MUST have an ID like this. $counter is initialized by post-highlights.

4. We wrap all the text information of a post inside a div with the ph_content class. Here you can use Template Tags such as the_author(), the_date(), the_category(), or anything you like.

1
2
3
4

<div class="ph_content">
    <h2><a class="ph_title" href="<?php the_permalink(); ?>"></a></h2>
    <p><?php echo $headline; ?></p>
</div>

Note that we are using the variable $headline we got in step 2.

5. The pictures go in a div of their own:

1
2
3
4
5

<div id="ph_picture-<?php echo $counter; ?>" class="ph_picture">
	  <a href="<?php echo the_permalink(); ?>">
	      <img src="<?php echo $imageurl; ?>" alt="" />
	  </a>
</div>

It MUST have an ID like this and the ph_picture class.

6. Thats All. Lets close the Loop:

1
2
3

		<?php $counter ++; ?>
	<?php endwhile; ?>
<?php endif; ?>

Dont forget to increment the $counter value.

7. Final Result

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<?php if ($highlightedPosts->have_posts()) : ?>
    <?php while ($highlightedPosts->have_posts()) : $highlightedPosts->the_post(); ?>
        <div id="ph_highlight-<?php echo $counter; ?>" class="ph_post">
            <div class="ph_content">
                <h2><a class="ph_title" href="<?php the_permalink(); ?>"></a></h2>
                <p><?php echo $headline; ?></p>
            </div>
            <div id="ph_picture-<?php echo $counter; ?>" class="ph_picture">
                <a href="<?php echo the_permalink(); ?>">
                    <img src="<?php echo $imageurl; ?>" alt="" />
		        </a>
            </div>
        </div>
    <?php endwhile; ?>
<?php endif; ?>
Navigation Elements

You can have a theme only with the Loop elements, but you may want to have some navigation elements, such as arrows and numbers to go from one post to another.

Here are the navigation elements. They are all optional:

Previous and Next navigation:

just add the following code:

1
2

<a id="ph-next-nav">next</a>
<a id="ph-prev-nav">previous</a>

You can add anything inside the “a” tags, or leave it empty and style it with height, width and a background image. Its up to you. And thats it, you dont need to do anything else. These links will behave as expected.

Numeric navigation:

All you have to do is add this to your theme:

1

<div id="ph-numeric-nav"></div>

And thats all! Post Highlights will dynamically insert an ul element with an li for each link. Here is an example of the automatically generated output. Now you will need to add some css rules to make it look beatiful.

1
2
3
4
5
6

<div id="ph-numeric-nav">
    <ul>
    	<li id="ph-numeric-nav-1"><a title="Post 1 Title">1</a></li>
    	<li id="ph-numeric-nav-2"><a title="Post 2 Title">2</a></li>
    </ul>
</div>

Settings.php

Post Highlights make it easy for you to add some dynamic settings to your theme. This settings are declared in this file and all you have to do is set the themeSettings attribute as described bellow. The plugin will handle everything. It will build the interface for you and save the data.

themeSettings

Here we register the settings by defining the themeSettings attribute. Each setting is a pair of key => value in the array where Key is the name of the setting (the name you will use to get the options later) and Value is the human readable name that will show up in the Settings page.

Registering your settings

Example:

1
2
3
4
5

$this->themeSettings = array(
    'width' => __('Width', 'ph'),
    'height' => __('Height', 'ph'),
    'arrow_colors' => __('Background color for the navigation arrows (e.g #FFCC00 or red)', 'ph')
);

themeSettingsDefaults

You can also set the defaul values for each setting. Its also a pair of key => value where key is the name of the setting (the same name you used on the array above and value is the default value for that setting

Example:

1
2
3
4
5

$this->themeSettingsDefaults = array(
    'width' => 690,
    'height' => 225,
    'arrow_colors' => "red"
);

useThemeJS

You will probably never want to set this to true. In fact, you dont need to add this line.

But if you are crazy enough, you can write your own javascript file to handle with the post highlight front end (you can also make a copy of the original front-end.js and make your custom JS.

If you set this to true, Post Highlights will look for a file called script.js on your theme folder and will not load the default JS file.

1

$this->useThemeJS = true;
Retrieving and using your settings

Post Highlights Class gives you the get_option() method for you to easily retrive the current value of your settings. You will probably want to use it on the index.php file, like in the example bellow (extracted from the default theme)

1
2
3
4
5
6
7
8
9
10

<style>
	#posthighlights_container #ph-next-nav,
	#posthighlights_container #ph-prev-nav {
	    background-color: <?php echo $this->get_option('arrow_colors'); ?>;
	}
	#posthighlights_container, #posthighlights_container .ph-canvas {
	    width: <?php echo $this->get_option('width'); ?>px;
	    height: <?php echo $this->get_option('height'); ?>px;
	}
</style>

style.css

You will also need a stylesheet to your theme. Just put a style.css file on your theme folder and it will be automatically included. Please refer to the default’s theme style.css for more tips.