Skip to content

Getting Started

Chris Van Patten edited this page Jul 14, 2014 · 13 revisions

UPDATED for Total Slider v1.1

Let's take a few minutes to create your first Total Slider template.

Where?

Create a directory in your currently active WordPress theme called total-slider-templates. Inside there, create a folder for your new template. We’ll call it mytemplate.

Inside your new folder, create a PHP file called mytemplate.php.

For now, let’s use something very similar to the default template PHP. We can, of course, customise this further later.

mytemplate.php

<?php
/*
Template Options

Crop-Suggested-Width: 600
Crop-Suggested-Height: 300
Disable-XY-Positioning-In-Admin: No
*/
?>
<?php if ($s->slides_count() > 0): ?>
	<ul class="ts-mytemplate">
	
	<?php while ($s->has_slides()): ?>
		<li id="ts-mytemplate-slide-<?php $s->the_identifier();?>"
			class="ts-mytemplate-slide <?php $s->draggable_parent();?>"
			style="background-image: url('<?php $s->the_background_url();?>');"
		>
			<a href="<?php $s->the_link();?>" class="ts-mytemplate-link">
				<div class="ts-mytemplate-overlay <?php $s->make_draggable();?>" style="left: <?php $s->the_x();?>px; top: <?php $s->the_y();?>px">
					<h2 class="ts-mytemplate-title"><?php $s->the_title();?></h2>
					<div class="ts-mytemplate-description">
						<p><?php $s->the_description();?></p>
					</div>
				</div>
			</a>
		</li>
	<?php endwhile ;?>
		
	</ul>
<?php endif; ?>

Take a brief look at this code. You might notice that it's similar to how WordPress themes work.

It first uses $s->slides_count() to check if there are any slides to show, and if there are (the result is greater than zero), we loop over them with while ($s->has_slides()). Then there are just a few $s->the_* functions to print out the title, description and so on for each slide.

Also, we use $s->make_draggable to make the overlay area, with the title and description, draggable in the editor (and $s->draggable_parent to make sure it can't be dragged outside the slide itself!). Don’t worry too much about these now.

For now, this PHP file is fine and meets our needs.

style.css

Your new template needs a CSS file, to define how your slides should look.

One of the easiest ways to get started customising your Total Slider output is to copy the default template’s CSS file and make changes to it.

Copy the style.css file from the Total Slider plugin directory's templates/default directory into your new mytemplate folder.

(You may also want to copy slider-desc-bg.png from the plugin's img folder into your theme's images folder, and update the .ts-mytemplate-overlay background, or you'll lose the overlay background colour!)

We’ll make a few changes to this file — first by adding a metadata section to the top. Just like with WordPress Themes and Plugins, this special comment at the top of the file will hold your Total Slider template’s name and other information.

Once we have done that, we will change the ts-default prefixes in the CSS to match your template — ts-mytemplate. Other than that, this CSS file will be just like the default template!

/*
Template Name: My Template
Template URI: http://www.totalslider.com/
Description: This is my first Total Slider Template
Author: You!
Author URI: http://www.totalslider.com/
Version: 1.0
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
*/

.ts-mytemplate {
	width: 600px;
	height: 300px;
	margin: 0 auto !important;
	padding: 0 !important;
	overflow: hidden;
	border: 1px solid #000;
	list-style: none !important;
}

.ts-mytemplate-slide {
	width: 600px !important;
	height: 300px !important;
	padding: 0 !important;
	margin: 0 !important;
	position: relative;
	background-position: center center;
	background-repeat: no-repeat;
}

.ts-mytemplate-slide .ts-mytemplate-link {
	display: block;
	width: 600px;
	height: 300px;
	position: absolute;
	top: 0;
	text-decoration: none
}

.ts-mytemplate-overlay {
	position: absolute;
	width: 300px;
	background: url(img/slider-desc-bg.png);
	padding: 5px 11px 11px;
	text-align: left !important
}

.ts-mytemplate-overlay .ts-mytemplate-title {
	font: 24px Georgia, serif;
	color: #FFF !important;
	text-shadow: 0 1px 1px black;
	padding: 0px 0 0 !important;
	margin: 0 0 5px !important
}

.ts-mytemplate-description {
	overflow: hidden;
	position: relative
}

.ts-mytemplate-description p {
	font: 14px/20px Helvetica, Arial, sans-serif;
	color: #FFF;
	text-shadow: 0 1px 1px black;
	margin: 0 !important
}

If you're already a CSS wizard, you should have no trouble making the changes to suit your specific needs.

Note: Our default CSS file makes use of !important in an attempt to override style declarations in the many situations that we can't easily predict. You probably won't need so many !importants in a custom Total Slider theme, which you can tailor to your WordPress theme's CSS cascade.

Let's make a simple change to the size of the slides — from the default 600x300, to say, 750x250.

/*
Template Name: My Template
Template URI: http://www.totalslider.com/
Description: This is my first Total Slider Template
Author: You!
Author URI: http://www.totalslider.com/
Version: 1.0
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
*/

.ts-mytemplate {
	width: 750px;
	height: 250px;
	margin: 0 auto !important;
	padding: 0 !important;
	overflow: hidden;
	border: 1px solid #000;
	list-style: none !important;
}

.ts-mytemplate-slide {
	width: 750px !important;
	height: 250px !important;
	padding: 0 !important;
	margin: 0 !important;
	position: relative;
	background-position: center center;
	background-repeat: no-repeat;
}

.ts-mytemplate-slide .ts-mytemplate-link {
	display: block;
	width: 750px;
	height: 250px;
	position: absolute;
	top: 0;
	text-decoration: none
}

.ts-mytemplate-overlay {
	position: absolute;
	width: 300px;
	background: url(img/slider-desc-bg.png);
	padding: 5px 11px 11px;
	text-align: left !important
}

.ts-mytemplate-overlay .ts-mytemplate-title {
	font: 24px Georgia, serif;
	color: #FFF !important;
	text-shadow: 0 1px 1px black;
	padding: 0px 0 0 !important;
	margin: 0 0 5px !important
}

.ts-mytemplate-description {
	overflow: hidden;
	position: relative
}

.ts-mytemplate-description p {
	font: 14px/20px Helvetica, Arial, sans-serif;
	color: #FFF;
	text-shadow: 0 1px 1px black;
	margin: 0 !important
}

Because we're changing the size of the slide, it's also worth us going into the PHP file, and modifying the crop height and crop width suggestions. These values in the PHP file are used to give a hint to users on how to crop their background images so they look best on the slide.

/*
Template Options

Crop-Suggested-Width: 750
Crop-Suggested-Height: 250
Disable-XY-Positioning-In-Admin: No
*/

Notice another option here -- if you wanted the title/description overlay to be in a fixed position, you could configure that in the CSS file, then set the Disable-XY-Positioning-In-Admin config directive to Yes. This would keep the title/description in a fixed position, and prevent the user from dragging it around in the Total Slider edit interface. (If you do this, you don’t need to set the draggable_parent and make_draggable stuff we saw earlier.)

For now, we'll leave that setting off, and retain the draggable title/description overlay.

mytemplate.js

You’ll also notice that you need to include a JavaScript file in your custom template before it will function properly. This JavaScript file is not included in the admin panel at all, but is instead used to run the front-end animations/transitions between slides.

By default, we use jQuery Cycle2 to handle slide transitions. It’s important to note that we do not automatically enqueue Cycle2 if you have the mytemplate.js file in your themes/mytheme/total-slider-templates/mytemplate folder (see here). Be sure to enqueue a copy yourself if you wish to use Cycle with custom JavaScript.

So, right now, you will need to download Cycle2 and include it, inline, in your mytemplate.js file. Then, after that, use code such as this to have the transitions between slides happen automatically:

jQuery('.ts-mytemplate').cycle({
    slides: '.ts-mytemplate-slide',
    timeout: 10000 // 10 seconds
});

For customisation, you could, for example, alter the time between slide transitions by editing the timeout value. The value is in milliseconds, so multiply the desired number of seconds by 1,000.

If you spend some more time getting acquainted with Cycle2, there are many more cool slide transition effects you can accomplish.

mytemplate.min.js

If you like, you can also use whatever minifier tool you desire to squeeze down your JavaScript file to make it as small and light as possible. Total Slider will use the .min.js file if it exists, unless SCRIPT_DEBUG is set to true in your wp-config.php file.

Key Points

Making your own Total Slider template is fairly simple and should be familiar to WordPress theme developers. You need:

  • A folder structure like this: wp-content/themes/my-wp-theme/total-slider-templates/mytemplate.
  • A mytemplate.php, mytemplate.js, and style.css file inside your template folder.
  • Your template’s PHP file to use the Template API to define how slides should be rendered in HTML.
  • A mytemplate.js JavaScript file which handles the transitions between the slides.
You can’t perform that action at this time.