NAV Navbar
Logo Wecodepixels logo 80px

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:

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

Creating posts with multiple pages

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

Adding 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:

  1. Adds the header. Be sure to insert it only once and on the first page.
  2. Adds a page's title. Be sure to insert it only once inside each page.
  3. 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

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

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

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

This sets the duration in milliseconds of the transition effect.

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

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

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

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.

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

Custom themes using CSS

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".

Adding a Navigation Bar

<?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', '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).

Example: 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".

Adding a 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=""]

API for developers

Sample code:

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

Finding the page/slide number using PHP

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 );
?>

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

Finding the page/slide number using JavaScript

Here is an example of the 'theiaPostSlider.changeSlide' jQuery trigger being used:

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

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

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).

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" (without the quotes).

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.

Changelog