While it is easy to use tcSlider to create simple slideshows that do things other sliders can't do, it's real power comes into play when you embedded content from other blocks or server interfaces (via AJAX) or add your own javascript to "program" your slideshow. It may help to think of tcSlider as more of a slideshow "framework" than a simple slideshow like other add-ons.  The documentation below explains both the simpler functionality of tcSlider as well as how to use the more advanced functionality.

Block Configuration Instructions

Each slider has it own settings that may or may not apply to the slides within the slider:

• Handle: a unique, user friendly name for each slider; this value is used by some of the advanced features of tcSlider.  If you will be creating only simple sliders you can leave this field blank and tcSlider will generate a handle for you.
• Height/Width: The size of the slider is fixed.  You may specify the size in any unit supported by CSS.
• Slide Order: determines the order in which slides are played.
  • Position: slides are played in order
  • Random: slide order is random
  • Slide Settings: the order is determined by the individual settings for each slide
• Default Transition: the default transition for all slides in the slider.
  • Use 'Slide Settings' to allow each slide to determine its own transition.
• Transition and View duration: the default animation and display times for each slide.
• Previous/Next Link: the text/html used for the basic previous/next links/buttons.
  • These values can be blank if you don't want links/buttons or will be creating them manually

Additionally, each slide has its own handle and can be assigned it's own transition effect, transition and view duration, and can specify which slide is should be the next slide or the previous slide.

Advanced Functionality

Adding Buttons to Update Slider

tcSlider supports simple next/previous links via the edit options.  In many  cases, however, you may not want to use these.  A far more powerful way to control to tcSlider is through custom links (HTML '<a>' tags). By using custom links you can specify the slide and slide transition to use, which means your slider need not operate as a simple linear slideshow.

tcSlider will automatically handle links using the following criteria:

1. Links should have the class 'tc-slider-link' to identify them as being a tcSlider custom link
2. Links must have a class that identifies the slider that they modify. tcSliders are distinguished by their handle so, for example, if you have a tcSlider with the handle 'myslider' then your custom link must have the class 'tc-slider-link-myslider'
3. tcSlider looks for two GET arguments to determine which the slide should be displayed and what transition to use. These are:
   1. tc-slide - value is the handle of the slide to be displayed or the special values 'slide-next' or 'slide-prev'
   2. tc-transition - value is a transition effect (e.g. fade, slide-left, slide-down, etc).
      For example, to specify that a link should load the 'first' slide and transition it with the fade effect use:
              <a href="#?tc-slide=first&tc-transition=fade"
                   class="tc-slider-link tc-slider-link-myslider">Link</a>
   3. two additional special classes are supported by tcSlider: 'tc-slider-linknext' and 'tc-slider-linkprev'. If either of these classes is present for a custom link, tcSlider will automatically apply the 'tc-disabled' class and the HTML 'disabled' attribute to the link when there is no "next" or "previous" slide for the current slide, respectively.
   4. another class that is supported for custom links is 'tc-active'. tcSlider will add the 'tc-active' class to the links that have an id equal to a slide handle whenever that slide is currently shown. For example, the following link will be marked active when the "contact-me" slide is visible:
              <a id="contact-me" href="#?tc-slide=contact-me&tc-transition=slide-left"
                   class="tc-slider-link tc-slider-link-myslider">Link</a>

Using a Concrete5 Block as a Slide

The tcSlider can use the output of Concrete5 blocks for the content of slides.  Content slides, for example, are actually essentially just instances of the Concrete5 HTML block.  Many other blocks may be use, though, not all will work with tcSlider.  You may need to experiment with different blocks to see if they will work with tcSlider.

Some blocks will not work with tcSlider.  Other blocks may require custom PHP code to be written for them to work properly.  The core Form block, for example, will display properly with tcSlider but because it posts back to the page the slider is on when the a form is submitted there is some extra work that need to be done in order to connect the form post to the slide that contains the form block.

Block output may be loaded once when the page is first loaded or dynamically each time before a slide is displayed.  Choose 'Yes' for 'Use Ajax for Blocks' if you want the block content reloaded each time the slide is displayed.

Except for content slides, to use a block with tcSlider you must first follow the steps below.  Depending on which version of concrete5 you are using these steps will be different:

If you are using concrete5 version 5.3.x - 5.4.x follow these steps:

1. Create an instance of the block you want to use as a slide and then copy the slide to the Concrete5 Global Scrapbook.  If the Global Scrapbook does not exist, you must first create it.  The tcSlider Edit panel will detect whether the Global Scrapbook exists and will give you the option to automatically create it. You may also go to the Scrapbook area in concrete5 Dashboard and add blocks to the Global Scrapbook directly.
2. Give the block a memorable name in the Scrapbook.  The tcSlider Edit panel will display the names of all of the blocks it recognizes.
3. Go to the page where you have a tcSlider (or where you want to create a slider) and edit/add the slider.
4. Finally, click the 'Add Block' button and select the block from the 'Block' dropdown.

If you are using concrete5 version 5.5.x follow these steps:

1. Create a stack named 'tcSlider'.  You may use a different stack name by setting a define named TC_SLIDER_STACK in your site.php.  The tcSlider Edit panel will detect whether the tcSlider stack exists and will give you the option to automatically create it.
2. Add a block to the tcSlider stack.
3. After you have added the block, click on the block in the stack and select 'Custom Template'.
4. In the 'Custom Template' dialog enter a name for the block.
5. Repeat steps 2-4 for additional blocks as desired.
6. Click 'Approve Changes' to "save" your changes to the stack.
7. Go to the page where you have a tcSlider (or where you want to create a slider) and edit/add the slider.
8. Finally, click the 'Add Block' button and select the block from the 'Block' dropdown.

If you upgrade a site from concrete5 version 5.4.x to 5.5.x and you are using tcSlider with block slides, you need to be aware that the Global Scrapbook (and other scrapbooks) will no longer be editable from the concrete5 dashboard.  Your tcSlider blocks will continue to work correctly so long as you don't edit them.  If you need to edit a tcSlide block, however, you will need to follow the steps above for concrete5.5.x.  You will have to create a new tcSlider stack, add blocks to the stack, and name each block in the stack.

Using a URL as a Slide

In much the same way that Concrete5 blocks can used as the source for slides, URLs may also be used to obtain slide content.  When editing a tcSlider click the 'Add URL' button to add an URL-based slide then type in the URL that you want to use. The URL may be fully qualified or may be a relative path.

tcSlider passes two POST argument to the slide URL that can be used to allow an URL to generate different content for different slides.  'slider' contains the slider handle, and 'slide' contains the slide handle.

The slider 'Use Ajax for URLs' option operates like the similar option for blocks.  If enabled, tcSlider will make an Ajax request to the URL to dynamically obtain new content each time the slide is displayed. If disabled, tcSlider will use Curl to fetch the content when the page loads; note that your installation of PHP must have Curl enabled in order for this to work.

As a security precaution most browsers do not allow Ajax requests between domains. So, if you intend to use an external URL for a slide, make sure you do not enable Ajax.

Frequently Asked Questions

Question:
Why can't I use the Concrete5 sitemap to choose a page for slide URLs?

Answer:
Slides are not complete pages, they are just chunks of HTML that become part of the page when embedded in a slider.  If you want to embed a complete page within the slider you can use something like the iframe block.

Question:
Can you provide an example of using a URL for a slide?

Answer:
Yes, tcSlider includes an very simple sample URL.  Take a look at the following file included in the add-on package:

<concrete5-install-dir>/packages/tc_slider/tools/helloworld.php

You can use this sample script in a tcSlider by using the URL:

/index.php/tools/packages/tc_slider/helloworld

To add your own slide URLs you would add a similar script to your site's top-level tools directory (<concrete5-install-dir>/tools) and reference it with an URL like:

/index.php/tools/helloworld

Question:
I just installed tcSlider and now my concrete5 edit bar is gone!

Answer:
This is almost always caused by a javascript error. tcSlider is not necessarily the cuplrit. Usually the site in question was experiencing javascript errors before tcSlider was installed, they just weren't visible.

Question:
I am getting a javascript error ("slider.slides[slider.slide] is undefined") when my site loads with tcSlider. What's wrong?

Answer:
Make sure you have not assigned any of your slides with a numeric handle. Some of the javascript functions in tcSlider accept either a handle or a slide index. If the handle is a numeric value, tcSlider will interpret it as an index instead.