Saturday, March 2, 2013

Integrating a JQuery Cycle image slider in TYPO3 6.0 without the need of installing an extension

There are a lot of JQuery image slider or slideshow extensions in TYPO3 TER, which (hopefully) all do work very well. Integration is mostly very easy - just install the extension, include some static TS and configure the plugin and there you go with a nice "Out of the box" Image Slider. Thit is surely good for a lot of people using TYPO3.

But some extensions come with their own included version of JQuery, which can't be disabled. Others include a lot of inline CSS and/or JS into the frontend, which also can't be disabled. And some extensions do not work correctly with TYPO3 6.0.

On the way looking for the "perfect" solution for a JQuery Image Slider in TYPO3, I decided not to use an extension (no worry about extension updates, breaking changes or incompatibility), but integration the slider directly into the TYPO3 website using default and well known TYPO3 techniques. The advantages of this is: full flexibility, easy administration and easy usage for editors.

This article shows how to create a JQuery image slider using Jquery Cycle, which is generated from a normal TYPO3 image content element. The slider includes a bullet navigation depending on the number of images.

Prerequisites
You need a working TYPO3 6.0 (lower versions should work as well) installation with CSS Styled Content installed and at least one template, so you actually are able to insert content on a page and see it's output in the frontend.

Integration into TYPO3
First of all, you need download the JQuery Cycle Plugin and upload it somewhere in your fileadmin directory (in this example fileadmin/templates/js/jquery.cycle.all.js).

Next, create a new JS file (fileadmin/templates/js/slider.js), where you put the JS for the JQuery Cycle slider. Insert the following content to the file.

$(document).ready(function () {
    $(".imageslider .csc-textpic-imagewrap").cycle({
        fx:'fade',
        pause:1,
        pager:'.slidernav',
        pagerAnchorBuilder:function paginate(idx, el) {
            return '<a class="' + idx + '" href="#" >•</a>';
        }
    });
});

Now, include the JQuery Cycle Plugin and the newly created JS file to your template. If you have not already included a version of JQuery to your site, make sure to include one.

page.includeJS {
  jquery = http://ajax.googleapis.com/ajax/libs/jquery/1.8.3/jquery.min.js
  jquery.external = 1
  cycle = fileadmin/templates/js/jquery.cycle.all.js
  slider = fileadmin/templates/js/slider.js 
}

The slider also requires some CSS for positioning of the bullet navigation. Include the following CSS to your sites CSS file.

.imageslider {
    position: relative;
    width: 300px;
    height: 225px;
    overflow: hidden;
}

.slidernav {
    position: absolute;
    z-index: 10;
    top: 170px;
    right: 20px;
}

.slidernav a {
    text-decoration: none;
    color: #ffffff;
    font-size: 40px;
    margin: 0 0 0 5px;
}

.slidernav a.activeSlide {
    color: #bbbbbb;
}

/* remove default bottom margin */
.imageslider .csc-textpic-image {
  margin: 0;
}

Please notice, that in this example I set the width and height of the image slider to a width of 300 pixel and a height of 225 pixel. This is'nt really necessary, but it makes it easier to position the bullet navigation to the bottom right.

As I don't like to override the default settings of CSS styled content or tt_content, I create a new frame, which the editor can select in the frame-dropdown of each content element.

Include the following to your root Page TSConfig.

TCEFORM.tt_content.section_frame {
     addItems.100 = Slider 
}

Now you must enable the new frame and include the HTML tags for the slider with the following TS.

tt_content.stdWrap.innerWrap.cObject {
  100 = TEXT
  100.value = <div class="imageslider"><ul class="slidernav"></ul>|</div>
}

That's all - the JQuery Cycle image slider is now ready for usage.

Usage
Create a new content element with images only and insert some images.


Set the "Indentation and Frames" to "Slider", the width of the images and the image alignment to 1 column.

Save the content element and you're done.

If you open the page in the frontend, you should see an image slider like shown on the screenshot below.


Conclusion
I hope this article gives you a perspective on what is possible with TYPO3's image content element and just some lines of TS, JS and CSS. If you want a next and previous button for the slider, no problem - just use the "prev" and "next" option of JQuery Cycle plugin.

As you have seen, it is not always necessary to install an extension to integrate an image slider to TYPO3. With the shown solution, editors can use TYPO3's default content elements and the site administrator has full control of the sliders features and can use all nice options of the JQuery Cycle plugin.

Please notice, that everything shown in this article is just an example on how a JQuery Cycle image slider could be integrated into TYPO3. Feel free to modify the settings to your own needs.

Update 15.05.2013
You have to make sure that the JS file, which enables the JQuery Cycle slider, gets the DIV-tag, which contain the container elements for the images. Below is an example for images, which are aligned "above, center". The second line contains the part, where you select the DIV with elements to cycle.

$(document).ready(function () {
    $(".imageslider .csc-textpic-center-inner").cycle({
        fx:'fade',
        pause:1,
        pager:'.slidernav',
        pagerAnchorBuilder:function paginate(idx, el) {
            return '';
        }
    });
});

No comments:

Post a Comment