Beginning Jssor

Foreword:
Over the past 4 years, a friend and I have worked on a web site for the Artists of our community where they can show off their work and we can publish relevant information about upcoming shows and other events. In order to attract visitors and encourage them to return periodically, I made heavy use of Jssor slideshows. This combined with intelligent algorithms provides visitors with a different show on each visit.

Technically, Jssor was ideal for this application; BUT its very power makes it hard to learn. This tutorial is designed to ease the learning curve for others.

Jean Vaucher (Aug. 2019)


  • Basic reference: http://www.jssor.com
  • JSSOR is a powerful package for dynamic Slideshows from MIT. Although it can be used to great effect with a minimum of coding, its huge number of features and examples makes it difficult to understand. Furthermore, the site organisation has changed from when I learned to use it in 2015. Before, you could easily download individual examples and learn from them; now, the code is "hidden". However, in our Tutorial folder, you will find the source code for all examples from the 2015 site. [Note: these old versions still seem to work OK ].

    The old site also provided a large number of already coded fun TRANSITIONS and Caption animations. The new site relies on an online Website Builder and Editor system [See the Demos - Skins - Tutorial - ... options on the Home page ]. In my view, this adds to the learning curve.

    Folder Contents

    LINK to enclosing Folder:

    A Simple Slider

        = Try it: demo0.html

    This is a simple slideshow looping over 3 images - no special effects, captions or navigation. It takes less than 50 lines of code. However, it handles images of various sizes: large ones are scaled to fit the "slide area" and smaller ones are centered.

    Part of the code is shown below. It looks very much like the first "standard Format Example" on JSSOR's development page; but our example has added a "trigger" to start the animation and uses a different FillMode (=5) to handle images of various sizes.

    In this version, there are clearly two parts to the code. The first half is JavaScript; the second HTML.

    In the first part, we start by loading the JSSOR package. Then comes an important function [ jssor_slider1_starter ] that animates the slideshow with a JssorSlider object based on the Options. This function is always called at the end of the page to start the show. We use color to indicate links between important variables: GREEN in this case.

    <body>
    
        <script type="text/javascript" src="js/jssor.slider.min.js"></script>
        
        <script>
            jssor_slider1_starter = function (containerId) 
            {
                var options = 
                {
                    $AutoPlay: true,     
                    $FillMode: 5,           
                    $ArrowKeyNavigation: true,  
                    $DragOrientation: 0 
                };
    
                var jssor_slider1 = new $JssorSlider$(containerId, options);
            };
        </script>
            
    <!-- ================================================================ -->
    
        <div id="slider1_container" style="position: relative;  
        				width: ...; height: ...;">                
          <!-- Slides Container -->
            <div u="slides" style="position: absolute; top: 0px; left: 0px; 
                 	width: ...; height: ...; overflow: hidden;  ">
               <div><img u="image" src="img/1.jpg" /></div>
            	... more images ...
            </div>        
        </div>
    
       <!-- Trigger -->
       <script>        
          jssor_slider1_starter('slider1_container');
       </script>
       
    </body>
    

    In the second half we have a large DIV (id="slider1_container") in which there is another container for the Slides ( <div u="slides" ... ). Each slide is represented by another <div> containing an <img> as well as any captions - if any. In this cas, we just show one slide coded as

    <div> <img u="image" src="img/1.jpg" /></div>

    All JSSOR demos have the same organization as this simple example:

    The order of the Container and the Starter is immaterial. They have been interchanged in demo0.html and demo0a.html. The only constant is that the Trigger must be at the end.

    Jssor has many options, but the 4 used in this example are the only ones we used for all the animations in our TRAM and Vitrine projects. The possible values for these options and their effect is documented by comments in the examples.

    In all our examples, the Slider only contains ONE element: the slide viewer; There are no control elements ( such as L and R arrows around it ) outside it. In theses cases, SlideR container is always the same size as the Slide container.

    width: 700px; height: 500px;

    A last thing to note is that JSSOR does not rely on the usual fixed ID or Class identifiers to discover and manage the various elements. Rather it uses a "u" notation, like:

    A final comment is that none of our demos or slideshows developped for the ART sites used CONTROL elements such as arrows or thumbnails. in these cases, the Slider container is always the same size as the Slide container

    Getting Fancy

    By default, new slides glide in from the right; but Jssor allows many other kinds of transitions. There is a special macro language to define new transitions and an editor to create them but, when starting out, it is easiest to copy the transitions that you find in demos and paste them into the Slider Starter Function.

    Try demo1.html which is the same as our first example with 3 transitions added. As shown below, this was accomplished by small additions to the Slider STARTER:

       jssor_slider1_starter = function (containerId) {
    
          var _SlideshowTransitions = [
             //Rotate in- out+
             { $Duration: 1500, $Zoom: 11, $Rotate: 0.5, ....  },
             //Rotate Axis up overlap
             { $Duration: 1200, x: 0.25, y: 0.5, $Rotate: -0.1, $Easing: ... },
             //Chess Replace TB
             { $Duration: 1600, x: 1, $Rows: 2, $ChessMode: { $Row: 3 }, ... }
          ];
    
          var options = {
          
             $AutoPlay: true,         
                ...   
    
             $SlideshowOptions: {                    
                $Class: $JssorSlideshowRunner$,      
                $Transitions: _SlideshowTransitions,   
                $TransitionsOrder: 1,                
                $ShowLink: true           
             }, 
          };
    

    Adding Captions

    Captions are additional graphic elements that one can add to a slide. The example at right shows one of our slides with 2 captions: an ID photo and a name box. Captions are obtained by adding <div> elements to the slide <div>. Size , appearance and positionning of captions follows the usual CSS rules and classes should be used to shorten the coding.

    Given a simple slide image:

    <div><img u="image" src="img/3.jpg"/> <div>
    Here is how we could add the name "Juan Aquino" 30px from the left.
       <div><img u="image" src="img/3.jpg"/>
          <div class="captionTram" style="left:30px;">
             Juan Aquino
          </div>
       </div>
    
    The size and other attributes of the enclosing text box are defined by the class. If we do nothing else, a caption will be fixed in place and appear at the same time as the slide image.

    Animation of a caption is done by adding "u=caption" and using a predefined transition. For example, t="Z" :

       <div><img u="image" src="img/3.jpg"/>
          <div u="caption" t="Z" class="photoID" style="left: 400px; ">
             <img src="photo/ja.png" />
          </div>                            
       </div>
    

    In addition, one must add the predefined caption transitions to the options

       jssor_slider1_starter = function (containerId) {
    
          var _CaptionTransitions = [];
            _CaptionTransitions["B"] = { $Duration: 900, y: -0.6, ... $Opacity: 2 };
            _CaptionTransitions["Z"] = {$Duration:900,$Zoom:1.8,$Easing: ...};
    
          var options = {
          
             $AutoPlay: true,         
                ...   
    
             $CaptionSliderOptions: {                    
                $Class: $JssorCaptionSlider$,             
                $CaptionTransitions: _CaptionTransitions,       
                $PlayInMode: 1,                             
                $PlayOutMode: 3                  
             }
          };
    

    Examples:

    Packaging the Slider

    After using Jssor over several years, I simplified things by creating a javascript file "slider_transitions.js" which contains the SLIDER_STARTER function with many of the predefined "fun" transitions and options found in the JSSOR demos.

    Our Gallery pages used this approach by including both Jssor and the STARTER function at the start:

       <script type="text/javascript" src="js/jssor.slider.min.js"></script>
       <script type="text/javascript" src="js/slider_transitions.js"></script>
    
    The pages then define the slideshow with a list of images and captions in the SLIDER_CONTAINER part. Below is the prototype for an early version of the TRAM web site; it starts with a HOME page followed by a slide show of artists and ends with a SPONSORS page.

    Transition Builder Tools

    The 2015 version of Jssor included some interesting tools to select and modify transitions:

    Postscript

    I deliberately left out of this tutorial certain topics which weren't used in the Artist Site. Although some of those features were used in the Examples that I used to learn Jssor:
    Slides of various sizes, Random slide transitions
    different-size-photo-slider.source.html
    Bullets, Arrows, Thumbs, 2 transitions
    banner-slider.source.html
    Caption animations chosen randomly + Bullets & Arrow Navigation
    image-slider.source

    Jssor References

    Ref: http://www.jssor.com