Quick Start Guide

This small guide will help you get your new plugin up and running in just a few minutes.

First of all, you need to download the plugin file and unzip it (if you're reading this, you've probably done so already). Now you need to do one of the following:

Option A:
1. In the WordPress administration panel, open the Plugins -> Add new -> Upload page.
2. Select and upload the theia-post-slider.zip file.
Option B:
1. Unzip the theia-post-slider.zip archive into your WordPress plugins folder located at /wp-content/plugins/.
2. Open your browser and go to your WordPress admin panel.
3. Open the Plugins -> Installed plugins page and activate the Theia Post Slider plugin.

For customizing the slider, open the Settings -> Theia Post Slider page.

Creating posts

The slider is primarily used on posts with multiple pages. In order to split up your post into multiple pages, you can use the "Insert Page break" button which can be found inside the post editor.

Insert Page break

Without the plugin, WordPress will display these pages using a navigation bar like this one:

Standard WordPress Navigation Bar

Using the Theia Post Slider plugin, the pages can be browsed like this:

Theia Post Slider Navigation Bar

Headers, footers and titles

You can add a separate header that will be displayed above the slider, and a footer that will be displayed below. These will remain visible throughout all the post's pages. You can also add a title for each one of the pages. You can use the buttons highlighted in the image below, which do the following:

Adds the header. Be sure to insert it only once and on the first page.
Adds a page's title. Be sure to insert it only once inside each page.
Adds the footer. Be sure to insert it only once and on the last page.

Here is an example that uses a header, a footer and a title for each page:

Theia Post Slider Shortcodes in Editor

And here is the result:

Theia Post Slider Shortcodes Preview

Start Slideshow button

You can add a "Start Slideshow" button to your slider by using our [tps_start_button label="Start slideshow" style="" class=""] shortcode. You can also simply press the first highlighted button in the image below and the shortcode will be added automatically.

Theia Post Slider Start Slideshow Button

The name of the button can be changed by modifying the label attribute. In addition, you can continue styling the button on your own using the two shortcode attributes we implemented - style and class. With "style" you can add custom CSS rules like on any other tag, and with "class" you can use a pre-existing CSS class. Below is an example of custom styling:

[tps_start_button label="Start slideshow" style="background-color: #f08100; color: #ffffff; font-size: 20px; width: 100%; height: 100px;" class=""]

Settings

You can change certain aspects of the plugin by opening the Settings -> Theia Post Slider page in the admin panel. You can instantly view the changes in the Live Preview section. The following settings are available:

Theia Post Slider Live Preview

Theme

This sets the slider's visual theme, mainly the previous and next buttons.

Transition effect

The animation effect used when moving from one slide to the other. There are 4 available effects: slide, fade, basic and none.

Transition duration (ms)

This sets the duration in milliseconds of the transition effect.

Navigation text

Between the previous and next buttons there is a text displaying the current and total number of slides. Here you can customize this text using the following variables: %{currentSlide} and %{totalSlides}.

Some examples:

Navigation text	Result
%{currentSlide} of %{totalSlides}	2 of 5
This is slide %{currentSlide} of %{totalSlides}	This is slide 2 of 5
%{currentSlide} / %{totalSlides}	2 / 5

Previous button text

The text that will be display on the "previous" button. Note that it works only on certain themes.

Next button text

The text that will be display on the "next" button. Note that it works only on certain themes.

Button width (px)

The width of the navigation buttons. Use this if you want both buttons to have the same width. Insert 0 for no fixed width. Note that it works only on certain themes.

Button behavior
- Enable slider on pages
  
  By default, the slider is enabled only on posts. This will enable it also on pages. Note that some themes may be incompatible with this option.
- Enable additional post navigation
  
  By default, the slider is used only for navigation between a post's pages. If a post has just one page, the slider is not displayed. By enabling this option, the slider will appear on all posts and can be used to navigate not only between pages, but also between different posts.
  
  If enabled, clicking the "previous" button on the first slide will open the previous post, and clicking the "next" button on the last slide will open the next post.

Refresh on every slide

A common use-case is to make the slider refresh the entire page on every slide. You can easily do this using the following settings:

Go to Settings -> Theia Post Slider -> Advanced.
Enable Refresh ads when navigating to another slide.
Set Refresh ads every N slide to 1.
Enable Refresh ads by refreshing the entire page.

Default themes

Theia Post Slider comes with over 200 different themes. Many of them are vector icons and support any custom color or size. They can be found in the "Settings -> Theia Post Slider" page in the admin panel.

Here is a showcase of some of the themes:

Theia Post Slider Themes

Carousel

Settings

You can change certain aspects of the carousel by opening the Settings -> Theia Post Slider page in the admin panel, and then navigating to the Carousel tab. The following settings are available:

Enabled

This is the global setting for enabling or disabling the carousel. This can also be set on a post-by-post basis.
Number of thumbnails displayed

The number of slide thumbnails displayed at the same time. The rest of the thumbnails cand be viewed by scrolling the carousel. This can also be set on a post-by-post basis.
Height (px)

The carousel's height. This will not stretch the thumbnails, since they are displayed using a best fit approach. This can also be set on a post-by-post basis.
Thumbnail spacing (px)

Sets the gap between thumbnails.
Vertical position

The carousel can be displayed either above the post or below.
Source image position

The plugin needs to extract a thumbnail image from each slide/page. This can be either the first or the last image found. You can also choose a custom thumbnail on a slide-by-slide basis.
Navigation Buttons

Here you can customize the carousel's previous and next buttons. You can match these settings with the ones from the main Theia Post Slider plugin, or choose something different.

Carousel for Theia Post Slider admin page

Post Settings

Some settings can be changed on a post-by-post basis.

Enabled

Either use the global setting, or forcefully enable or disable the carousel.
Number of thumbnails displayed

Override the number of slide thumbnails that are displayed at the same time. Leave blank to use the global setting.
Height (px)

Override the carousel's height. Leave blank to use the global setting.

Carousel for Theia Post Slider admin page

Custom Thumbnails

Usually, a slide's thumbnail is the first or last image found in that particular slide, depending on what settings you are using. However, in case you have multiple images in your slides, you can override this setting by adding the custom class cftps-featured on the image you want to use as thumbnail.

First, inside the post editor, click on the image you want to use. Then click on the edit button that has a pencil icon.

Carousel for Theia Post Slider admin page

Second, add cftps-featured inside the Image CSS Class field. If you need to have multiple CSS classes, you can separate them using spaces.

Carousel for Theia Post Slider admin page

Finally, click on Update inside the Image Details window, and again Update to save the changes to your post.

Customizations

Custom themes

To aid you in writing your custom theme's CSS, here is the basic HTML structure of the slider:

<div class="theiaPostSlider_nav _upper">
    <a class="_prev">
        <span class="_1"></span>
        <span class="_2">Previous</span>
        <span class="_3"></span>
    </a>
    <span class="_text"></span>
    <a class="_next">
        <span class="_1"></span>
        <span class="_2">Next</span>
        <span class="_3"></span>
    </a>
</div>
<div class="theiaPostSlider_slides">...</div>
<div class="theiaPostSlider_nav _lower">
    [same as the first navigation bar]
</div>

If disabled, the previous and next buttons use a <span> tag instead of an <a> tag and have the "_disabled" class:

<span class="_prev _disabled">...</span>

If the default themes are not visually compatible with your WordPress theme or you simply want to customize your slider as much as possible, you can easily create a custom theme. All you need is some knowledge of CSS. This chapter will help you get started.

First, go into the plugin's CSS folder wp-content/plugins/theia-post-slider/css and copy the base.css file and paste it with another name such as my-theme.css. The file now contains the basic CSS rules needed for the slider to function, and you can now edit it to your liking. You should also review some other themes' CSS files to see how they are made.

Second, you need to activate the new theme. Go into the plugin's settings page Settings -> Theia Post Slider in the admin panel and select your new theme, which should be entitled My Theme if you named your file my-theme.css.

CSS Examples

Here are some CSS rules you can use for common scenarios.

Hiding the "Previous" button on the first slide:

.theiaPostSlider_nav._slide_number_0 ._prev {
    display: none;
}

Showing a full-width "Next" button:

.theiaPostSlider_nav ._buttons {
    display: block !important;
}

.theiaPostSlider_nav ._button {
    display: block;
    background: lightgrey;
}

Showing fully custom buttons:

.theiaPostSlider_nav ._button {
    background: lightgrey;
    border: 1px solid darkgray;
    border-radius: 16px;
    color: purple;
}

Using custom widths and hiding the previous button on the first slide

.theiaPostSlider_nav ._button {
    font-size: 30px;
    padding: 10px 0;
}
.theiaPostSlider_nav ._button svg {
    vertical-align: middle;
}
.theiaPostSlider_nav ._prev {
    width: 32% !important;
}
.theiaPostSlider_nav ._next {
    width: 62% !important;
}
.theiaPostSlider_nav._slide_number_0 ._prev {
    display: none;   
}
.theiaPostSlider_nav._slide_number_0 ._next {
    width: 100% !important;  
}

In this example you also need to set Navigation Bar -> Horizontal Position to Full-width. Here is the end result:

First slide

Second slide

API

Get slide number with PHP

You can find the slide's number using the global $page variable.

Here is an example that adds the page number inside a slide using the standard "the_content" filter from WordPress:

<?php
function the_content_custom( $content ) {
    global $page;

    $content .= "We are on slide number $page";

    return $content;
}
add_filter( 'the_content', 'the_content_custom', 10, 2 );
?>

Get slide number with JavaScript

If you need the slide number inside JavaScript, you can use the theiaPostSlider.changeSlide jQuery trigger.

jQuery(document).bind('theiaPostSlider.changeSlide', function(event, slideIndex) {
    alert('The user has navigated to slide number ' + (slideIndex + 1));
});

JavaScript events

The plugin offers a humble API for developers who wish to extend its functionality. Right now you can hook your code into the tps.changeSlide event, which triggers whenever the user navigates to another slide. Note that this event is fired after the slide has been loaded via AJAX (if applicable).

jQuery(document).on('theiaPostSlider.changeSlide', function(slideNumber) {
    alert('We are on slide number ' + slideNumber);
});

WordPress hooks

There are several filters and actions you can use to further customize the plugin:

tps_the_content_before
tps_the_content_before_header
tps_the_content_before_current_slide
tps_the_content_after_current_slide
tps_the_content_after
tps_is_compatible_post

The next sections will explore some of these hooks and create custom functionality around them.

For further reading we recommend diving into the plugin's source code.

<?php
if (class_exists('\WeCodePixels\TheiaPostSlider\Helper')) {
    echo \WeCodePixels\TheiaPostSlider\Helper::getNavigationBar(); 
}
?>

You can manually add a Navigation Bar by introducing this code into your single.php page, in your theme's folder, between PHP tags:

We strongly suggest using a child theme in order to not lose your added Navigation Bar when updating your theme.

Adding Content Above or Under Slider

The code needs to be between PHP tags and should look something like this:

<?php 
function my_custom_function( $html, $content ) {
    $html .= "Testing 1 2 3. Put desired content here.";

    return $html;
}
$priority = 10;
add_filter( 'tps_the_content_before', 'my_custom_function', $priority, 2 );
add_filter( 'tps_the_content_after', 'my_custom_function', $priority, 2 );
?>

$priority can take different values depending on where you want to place your text. This is especially useful when using the Carousel add-on. If you want your text to be shown above the Carousel, then you need to set $priority to be lower than 10, or higher if otherwise.

You can also add different short codes by changing the $html line with something like this:

<?php 
$html .= do_shortcode( "[some_short_code]" );
?>

You can also use the 'tps_the_content_before_header' filter to display text after the [tps_header] shortcode. Simply change the last two lines from the code above with:

<?php
add_filter( 'tps_the_content_before_header', 'my_custom_function', $priority, 2);
?>

You can add text, short codes or whatever else you might need above or under the slider by using our tps_the_content_before and tps_the_content_after filters.

This code can be added in your theme's functions.php file, although we strongly suggest using a child theme in order to not lose these changes after updating your theme.

Adding Between the Content of a Slide and Slider

The code needs to be between PHP tags and should look something like this:

<?php
function my_custom_function( $html, $content ) { 
    $html .= "Testing 1 2 3. Put desired content here.";

    return $html;
}
add_filter( 'tps_the_content_after_current_slide', 'my_custom_function', 10, 2 ); 
add_filter( 'tps_the_content_before_current_slide', 'my_custom_function', 10, 2 );
?>

You can also add text, short codes or whatever else you might need between the content of a slide and the slider by using our tps_the_content_after_current_slide, tps_the_content_before_current_slide filters.

You can add your code in your theme in functions.php (although we suggest using a child theme in order to not lose these changes after updating your theme).

Adding category names for prev/next post buttons

Here is the code to do so - you can add it inside the functions.php of your child-theme, preferably:

<?php
function my_custom_tps_options_get( $value, $optionId, $optionGroups ) {
    if ( ! in_array( $optionId, array( 'prev_text_post', 'next_text_post' ) ) ) {
        return $value;
    }

    global $post;
    $category = null;

    // Check for Primary Category (via the Yoast SEO plugin).
    if ( class_exists( 'WPSEO_Primary_Term' ) ) {
        $category = new WPSEO_Primary_Term( 'category', $post->ID );
        $category = $category->get_primary_term();

        if ( $category !== false ) {
            $category = get_category( $category );
        }
    }

    // Simply get one of the categories.
    if ( ! $category ) {
        $categories = wp_get_post_categories( $post->ID, array( 'fields' => 'all' ) );

        if ( count( $categories ) > 0 ) {
            $category = $categories[0];
        }
    }

    if ( $category ) {
        switch ( $optionId ) {
            case 'prev_text_post':
                $value = 'Previous ' . $category->name . ' post';
                break;

            case 'next_text_post':
                $value = 'Next ' . $category->name . ' post';
                break;
        }
    }

    return $value;
}

add_filter( 'tps_options_get', 'my_custom_tps_options_get', 10, 3 );
?>

Normally you can set a custom title for your previous / next post buttons inside the Admin -> Theia Post Slider -> Navigation Bar page, and optionally you can enable the Enable additional navigation between posts and Only for posts from the same category options. If you want to further customize the buttons, you can make them display the actual category you are browsing. For example if the current post is in the "Recipes" category, you can make your next button show "Next Recipe post".

Tracking pageviews

Theia Post Slider supports several analytics scripts: Google Analytics, Piwik, StatCounter, and Quantcast. It makes the appropriate JavaScript calls for registering pageviews each time a user navigates to a particular slide (i.e. loads the page or presses the "previous" or "next" buttons). Please note that:

The actual number of pageviews of course depends on your visitors and their particular behavior.
The analytics script might identify you as the website's admin and exclude your own traffic from the reports as to not skew them.
If you are using any ad blocker it will prevent any of your pageviews from being tracked.

Compatibility with other plugins

The plugin has been successfully tested with a wide range of plugins. Some, however, require a few extra settings to work properly.

Lightbox plugins

Not all lightbox plugins will work with Theia Post Slider if the "Load slides efficiently using AJAX" option is enabled. We recommend using the popular Responsive Lightbox by dFactory with the following options:

Lightbox script: FancyBox
Custom events: Enable
Events: theiaPostSlider.changeSlide

Related Posts plugins

Not all Related Posts plugins will work with Theia Post Slider. We recommend using Related Posts by Zemanta.

Embedded tweets

In the admin panel, go to Settings -> Theia Post Slider -> Advanced. Check the Do not cache rendered HTML option.

Social Locker by OnePress

In the admin panel, go to Social Lockers -> Common Settings. Check the I use a dynamic theme option, and add the following to the jQuery Event field: theiaPostSlider.changeSlide.

Simple Custom Post Order

If you use the Enable additional navigation between posts option and also need to change the order of your posts, you can use the Simple Custom Post Order plugin.

Quick Start Guide

Creating posts

Headers, footers and titles

Start Slideshow button

Settings

Refresh on every slide

Default themes

Carousel

Settings

Post Settings

Custom Thumbnails

Customizations

Custom themes

CSS Examples

Using custom widths and hiding the previous button on the first slide

API

Get slide number with PHP

Get slide number with JavaScript

JavaScript events

WordPress hooks

Adding another Navigation Bar

Adding Content Above or Under Slider

Adding Between the Content of a Slide and Slider

Adding category names for prev/next post buttons

Tracking pageviews

Compatibility with other plugins

Changelog