EXT: Simple Slideshow 2¶

What does it do?¶

Simple Slideshow 2 provides slideshow capability to Typo3 in the form of a plugin element that is inserted as content, just like any other type of content. The main benefit of Simple Slideshow 2 when compared with other slideshow extensions, is that files need only be uploaded to the selected folder on the server for them to be available to the slideshow; You may use FTP, the Filelist module, or any other method you can think of... If the image file is in the folder, it's available to be displayed by the slideshow automatically. You don't need to create individual records for each image.

Performs out-of-the-box as a non-clickable banner rotator. A banner rotator extension for Simple Slideshow 2 that allows defining links for particular images will be released in the near future.

See the Youtube video screencast: http://www.youtube.com/watch?v=PnHFNm7v_9s

Typo3 Developers:¶

Simple Slideshow 2 is also extendable. This means it's possible to create multiple different methods of displaying images, whereby the same principle applies; If the image is in the folder, it's accessible to be displayed. To read more about this feature, see the Extension Development chapter.

Screenshots¶

I would have included some screenshots of how the slideshow actually looks in the front end, but it would just be a screenshot of an image, which isn't particularly useful, so here are some shots from the backend, instead.

The required settings tab

The settings tab for the default slideshow effect

EM Settings¶

In the EM, there are two settings which have global influence over the extension. These are:

• Allowed Image Extensions: This setting is a pipe-separated list of allowed extensions. Only files with these extensions will be made available for display by the slideshow. By default allowed image types are: jpeg, jpg, png and gif.
• Configuration PID: If the cache file cannot be found, the Flash slideshow makes a call to a page on the site using a predetermined TypeNum to generate the cache file. This is the PID of the page to be used as the target for that call. By default, the root page has a PID of 1, but if you should have a need to specifically set a page (for example, if you only want to include the static template on the page the slideshow appears on), you may do that here.

Constants Reference¶

Constants available for plugin.tx_simpleslideshow2_pi1

Setup Reference¶

Setup properties available for plugin.tx_simpleslideshow2_pi1

Overview¶

The basic idea of Simple Slideshow 2 is to create a cache file that outputs a JSON-ised configuration array. This is then read by the Flash. There are some default properties in the configuration array, and a custom sub-array, containing the configuration specific to the Simple Slideshow 2 extension that is being used to output the slideshow functionality. The default slideshow effect is also configured as a separate extension (though it is integrated), in this regard. You can see this by looking at the output from the cache file for a plugin configured to use the default effect. Here's an example of the JSON output from the site I took the screenshots from:

{"imageFiles":["http:\/\/example.com\/fileadmin\/user_upload\/slideshow\/Chrysanthemum.jpg","http:\/\/example.com\/fileadmin\/user_upload\/slideshow\/Desert.jpg","http:\/\/example.com\/fileadmin\/user_upload\/slideshow\/Hydrangeas.jpg","http:\/\/example.com\/fileadmin\/user_upload\/slideshow\/Jellyfish.jpg","http:\/\/example.com\/fileadmin\/user_upload\/slideshow\/Koala.jpg","http:\/\/example.com\/fileadmin\/user_upload\/slideshow\/Lighthouse.jpg","http:\/\/example.com\/fileadmin\/user_upload\/slideshow\/Penguins.jpg","http:\/\/example.com\/fileadmin\/user_upload\/slideshow\/Tulip.jpg"],"width":"700","height":"120","cornersFile":"http:\/\/example.com\/typo3conf\/ext\/simpleslideshow2\/res\/corners.png","default":{"cycleMode":"0","delay":"5","transitionDelay":"1"}}

As you can see, the last object is keyed as default . Therefore, in the AS3 class built to receive this configuration array (the default slideshow effect), it looks in the default object for its specific configuration.

The cache file itself checks to see if the folder containing the images has been modified each time it is called. If it has, then internally it calls the URL that generates a new cache file.

If the cache file doesn't exist, (each time you click the save button whilst in a Simple Slideshow 2 plugin element, it automatically deletes the cache file for that element) then the flash will use the name of the cache file to construct the URL it can call that generates a new cache file. The URL is available on any page on the type specified by the plugin.tx_simpleslideshow2_pi1.typeNum constant. The tt_content element UID must also be specified. A specific PID is also used, as set in the EM. So we end up with 3 parameters that build the cache filename, for example: 1_34_699.php. The Flash then reconstructs this into the URL that regenerates the cache:

http://example.com/index.php?id=1&elid=34&type=699

Thus, we have a robust and efficient caching mechanism, that enables the extension to dynamically use all the images in the specified folder, without the need to create database records or otherwise complicate matters.

Extensions of Simple Slideshow 2 hook into the JSON configuration process, and do whatever manipulation is necessary to get the required configuration options passed to the Flash. Therefore, each extension of Simple Slideshow 2 automatically benefits from this caching mechanism.

Required Files¶

• typo3conf/ext/simpleslideshow2_static/ext_localconf.php
• typo3conf/ext/simpleslideshow2_static/ext_tables.php
• typo3conf/ext/simpleslideshow2_static/locallang_db.xml
• typo3conf/ext/simpleslideshow2_static/slideshow_flexform.xml
• typo3conf/ext/simpleslideshow2_static/res/simpleslideshow2_static.sw f

Other files, such as ext_icon.gif and ext_emconf.php will be made automatically by the kickstarter.

<?php
if (!defined ('TYPO3_MODE')) {
        die ('Access denied.');
}

$GLOBALS['T3_VAR']['ext']['simpleslideshow2']['extensions']['simpleslideshow2_static'] = array(
        'jsonOutputHook' => 'EXT:simpleslideshow2_static/class.tx_simpleslideshow2_static_jsonHook.php:tx_simpleslideshow2_static_jsonHook',
        'dropDownTitle' => 'LLL:EXT:simpleslideshow2_static/locallang_db.xml:dropDownTitle.simpleslideshow2_static'
);
?>

<?php
if (!defined ('TYPO3_MODE')) {
        die ('Access denied.');
}
t3lib_extMgm::addStaticFile($_EXTKEY,'static/default_setup/', 'Default Setup');
?>

<sheets>
        <simpleslideshow2_static>
        …

Included Files¶

• typo3conf/ext/simpleslideshow2_static/class.tx_simpleslideshow2_sta tic_jsonHook.php
• typo3conf/ext/simpleslideshow2_static/static/default_setup/setup.txt

As we've seen in ext_localconf.php, there is an included file for the json hook. There's also a reference to an included static template.

function jsonHook(&$arrJson, $effectKey, $row, $obj) {

        //Get the TS config
        $conf = $GLOBALS['TSFE']->tmpl->setup['plugin.']['tx_simpleslideshow2_static.'];

        $arrTmp = array();

        //Get specified values in the flexform, or set default values
        $arrTmp['fadeInDelay'] = ($tmp = $obj->pi_getFFvalue($row['pi_flexform'], 'fadeInDelay', $effectKey)) ? $tmp : $conf['fadeInDelay'];

        //arrJson is passed by reference, so we add the configuration variables we just set to a sub-object, keyed using the passed effectKey variable.

        //In the AS3 code, the code will need to parse this object.
        $arrJson[$effectKey] = $arrTmp;
}

plugin.tx_simpleslideshow2_static {
        fadeInDelay = 99
}

Code Listing¶

var blah:SlideShow;

package {

        import com.greensock.TweenMax;
        import flash.events.*;
        import flash.display.*;
        import flash.utils.*;
        import flash.net.*;

        public class SlideShow extends Sprite {

                private var config:Object;
                private var stg:Object;

                private var slideA:Sprite = new Sprite();
                private var slideB:Sprite = new Sprite();
                private var imgLoaderA = new Loader();
                private var imgLoaderB = new Loader();
                private var imgListPointer:int = -1;

                private var t:Timer;

                public function SlideShow(config:Object) {

                        this.config = config;
                        this.stg = config['stage'];

                        trace("SlideShow");

                        if(this.config['imageFiles'] == undefined) {
                                this.stg.notifyError("No list of images to display");
                                return;
                        }

                        if(getQualifiedClassName(this.config.imageFiles) != "Array") {
                                this.stg.notifyError("No list of images to display");
                                return;
                        }

                        if(this.config['simpleslideshow2_static'] == undefined) {
                                this.config['simpleslideshow2_static'] = new Object();
                                this.config.simpleslideshow2_static['fadeInDelay'] = 1;
                        }

                        if(getQualifiedClassName(this.config.simpleslideshow2_static) != "Object") {
                                this.config['simpleslideshow2_static'] = new Object();
                                this.config.simpleslideshow2_static['fadeInDelay'] = 1;
                        }

                        if(this.config.simpleslideshow2_static['fadeInDelay'] == undefined) {
                                this.config.simpleslideshow2_static['fadeInDelay'] = 1;
                        }

                        addChild(this.slideA);
                        this.slideA.addChild(this.imgLoaderA);
                        this.slideA.alpha = 0;
                        this.imgLoaderA.contentLoaderInfo.addEventListener(Event.COMPLETE, firstImgLoaded);
                        this.imgLoaderA.contentLoaderInfo.addEventListener(IOErrorEvent.IO_ERROR, loaderError);
                        this.imgListPointer = this.getRandomIndex();
                        this.imgLoaderA.load(new URLRequest(this.config.imageFiles[this.imgListPointer]));
                }

                private function firstImgLoaded(evt:Event):void {

                        TweenMax.to(slideA, this.config.simpleslideshow2_static.fadeInDelay, {alpha: 1});
                }



                private function getRandomIndex() {

                        var tmp:int = this.imgListPointer;

                        if(this.config.imageFiles.length == 1) {
                                return 0;
                        }

                        while(tmp >= this.config.imageFiles.length || tmp == this.imgListPointer) {
                                tmp = Math.round(Math.random() * (this.config.imageFiles.length - 1));
                        }
                        return tmp;

                }

                function loaderError(evt:IOErrorEvent):void {

                        var tgt:Object = evt.target;
                        var file = IOErrorEvent(evt).toString().match(/URL: (.+?)"/);
                        trace("Couldn't load file: " + file[1]);

                        for(var i:* in this.config.imageFiles) {

                                if(this.config.imageFiles[i] == file[1]) {

                                        trace("Removed " + this.config.imageFiles[i] + " from list of images to display");
                                this.config.imageFiles.splice(i, 1);
                                        this.imgListPointer = this.getRandomIndex();
                                }
                        }
                        tgt.loader.load(new URLRequest(this.config.imageFiles[this.imgListPointer]));
                }

        }
}

Code Analysis¶

In the .fla file, we define the class. If you don't do this, the class won't be accessible to the main flash file the compiled extension SWF is loaded into.

The resulting SWF file must be named the same as the extension key. Therefore, in this instance, the filename is simpleslideshow2_static.swf

In the SlideShow class, there are a few important things to notice. The class must extend sprite (or another DisplayObject object) as it's added to the stage with an addChild statement. Therefore, any displayable elements in the class must be added to the object using addChild, also.

The config object has a "stage" element, that is a reference to the stage object. There is a function on the stage named notifyError which accepts a string. As seen in the code, the first two error checks call this function to inform the user there's a problem.

Other than that, you can do what you want with the code. For development, I used the following stub code in the .fla file:

import com.adobe.serialization.json.JSON;

var dummyJSON:String = '{"imageFiles":["http:\/\/example.com\/fileadmin\/user_upload\/Billeder\/Forsiden Blah\/Jellyfish.jpg","http:\/\/example.com\/fileadmin\/user_upload\/Billeder\/Forsiden Blah\/Koala.jpg","http:\/\/example.com\/fileadmin\/user_upload\/Billeder\/Forsiden Blah\/Lighthouse.jpg","http:\/\/example.com\/fileadmin\/user_upload\/Billeder\/Forsiden Blah\/Penguins.jpg","http:\/\/example.com\/fileadmin\/user_upload\/Billeder\/Forsiden Blah\/Tulips.jpg"],"width":"464","height":"100","cornersFile":"http:\/\/example.com\/typo3conf\/ext\/simpleslideshow2\/res\/corners.png","customSlideShow":"http:\/\/example.com\/typo3conf\/ext\/simpleslideshow2_static\/res\/simpleslideshow2_static.swf","simpleslideshow2_static":{"fadeInDelay":"5"}}';

var config:Object = JSON.decode(dummyJSON);
config['stage'] = this;

var whatever:SlideShow = new SlideShow(config);

addChild(whatever);

function notifyError(error:String):void {
        var warning:TextField  =  new TextField();
        warning.autoSize = TextFieldAutoSize.LEFT;
        addChild(warning);
        warning.text = "Error: "+error;
}

0.0.1¶

17