XML Flash Slideshow v4 Help    |    Support Home    |    DWUser.com Home  Download Help PDF (29MB)    |    Search:

Slideshow / Javascript Interfacing

Important Note: This topic is only applicable to advanced users and developers.    Experience with Javascript is required.

Tip: You can also reference specific images and galleries directly through the page URL by using Permalinks.  See the Using Permalinks topic for more information.  It is recommended that you review the permalinks topic for roundness of knowledge even if you don't intend to use the feature.

The XFS v4 includes built-in support for interaction with the host HTML page through javascript.    This allows the HTML page to use javascript to both track the slideshow's status and control it.  This feature is implemented through the com.dwuser.ss4.core.SlideshowInterface class which is detailed in the API Reference.    This topic provides details on how to use this feature.

Call Types

There are two types of supported calls:

  • Outgoing calls - These calls are made automatically from the slideshow to the host page to notify of the current state or request information.  You define these methods within your page.
  • Incoming calls - The slideshow automatically listens for calls to certain methods in the host page. When these methods are called by javascript in the host page, actions are automatically taken by the slideshow. You call these methods within your own scripts.

In the code below, image and gallery UniqueIDs are referenced.  These are automatically assigned identifiers which each image and gallery has based on its position within the gallery and/or the gallery's position within the slideshow. Gallery UniqueID's have the following format: gallery_0 where the integer represents the gallery's 0-base index within the slideshow.  Thus the preceding example represents the first gallery.  Image UniqueID's have the following format: image_0_5 where the first integer represents the gallery's 0-base index within the slideshow, and the second integer represents the image's 0-base index within the gallery.  Thus the preceding example represents the sixth image in the first gallery.

Important: In the code below, image and gallery UniqueIDs are referenced.  These are special identifiers which can be used to reference specific galleries or even specific images in a specific gallery.  They are based on either the unique ID values assigned to the images and/or galleries, or their numeric indices within the slideshow or an individual gallery.  Before proceeding, it is important to review The UniqueID Format in the Using Permalinks topic.  This explains in detail the format used to reference individual galleries and images.

Details and Examples for Outgoing Calls

Important note: When placing each of the following receiver blocks in your HTML page, it is best to place them before the slideshow to ensure that everything works properly.

Note: Use of javascript interaction is not currently suported when there is more than one slideshow in a given page.    To work around this, you can place each slideshow in a separate HTML page, when display them in the main page using <iframe>'s.

Method Name/Signature Description
XMLFlashSlideshow_v4_getInitialViewID():String

As the slideshow is initializing, this method is called automatically in the host page. If the method is defined and returns a valid string value, the layout view corresponding to this return value will be opened as the initial view. For example, you might have defined the following view in your Layout XML in the XML configuration file: <view id="demoView" ... > . To dynamically make this view display first, the following method should be added to a javascript code block in your HTML page:

   <script language="javascript">

   function XMLFlashSlideshow_v4_getInitialViewID()
   {
    return "demoView";
   }
   </script>
       

XMLFlashSlideshow_v4_getInitialImage():String

Before the slideshow automatically opens the initial gallery, this method is called automatically in the host page. It allows you to override which gallery and/or image is displayed initially. If the method is defined and returns a valid UniqueID value, the gallery and/or image corresponding to the returned UniqueID will be opened. For example, the following javascript code block in your HTML page would make the third image in the first gallery open initially:

   <script language="javascript">
   function XMLFlashSlideshow_v4_getInitialImage()
   {
    return "0->2";
   }
   </script>
        

 

This code, because it only specifies a gallery id, would open the first image in the gallery with an ID value of myGallery :

   <script language="javascript">
   function XMLFlashSlideshow_v4_getInitialImage()
   {
    return "myGallery";
   }
   </script>
        

 

Note: If no custom XMLFlashSlideshow_v4_getInitialImage function has been defined and a xfs4_gid permalink URL parameter has been passed, a function is automatically defined to enable automatic permalinking.  For more information, see Using Permalinks.

XMLFlashSlideshow_v4_notifyReadyForImageSet():void

This method is automatically called in the host page once the slideshow has initialized to the point of being ready to accept incoming calls. See the table below for more information on incoming calls, which allow your scripts to control the slideshow. For example, the following javascript code block could be placed in your HTML page:

   <script language="javascript">
   function XMLFlashSlideshow_v4_notifyReadyForImageSet()
   {
    // This method doesn't return anything...
    alert('The slideshow says it is ready for incoming calls!');
   }
   </script>
  

XMLFlashSlideshow_v4_syncGallery(JSONInfoObject:String):void

This method is automatically called in the host page whenever a gallery is opened. It allows your page to track the current gallery that is open in the slideshow. You could use this to display pertinent gallery-related information in the HTML page.

The passed string is a JSON string which evaluates to an object with the following properties:

  • uniqid - This is the standard UniqueID associated with the gallery.  It is either the gallery's numeric index, or its associated unique ID value.  This value can be used for other calls, such as the XMLFlashSlideshow_v4_requestGallery(uniqid:String) call documented below.
  • uniqidOLD - This is the UniqueID for the gallery in the old deprecated format (e.g. gallery_0).  It is only included for backwards compatibility.
  • galleryID - Same as the uniqid property.  Included for completeness.

To use the information in the JSON object, an eval() call must be used on the string.  For example, the following javascript code block could be placed in your HTML page to display an alert every time a new gallery is opened:

   <script language="javascript">
   function XMLFlashSlideshow_v4_syncGallery(jsonString)
   {
    // This method doesn't return anything...
    var infoObject = eval(jsonString);
    alert('The slideshow has just opened a gallery.  Here is its UniqueID: ' + infoObject.uniqid);
   }
   </script>
  

XMLFlashSlideshow_v4_syncImagesStart(JSONInfoObject:String):void

This method is automatically called in the host page whenever an image starts to be opened/synced. It allows your page to track the current image that is open in the slideshow. You could use this to display pertinent image-related information in the HTML page, or to track which image is open and store the state in a cookie, etc. Or, you could use a package such as SWFAddress to enable back/forward button browser navigation.

The passed string is a JSON string which evaluates to an object with the following properties:

  • uniqid - This is the standard UniqueID associated with the image.  It is either the gallery's numeric index, or its associated unique ID value, followed by -> and the image's numeric index or its associated unique ID value.  This value can be used for other calls, such as the XMLFlashSlideshow_v4_setImage(uniqid:String) call documented below.
  • uniqidOLD - This is the UniqueID for the image in the old deprecated format (e.g. img_0_5).  It is only included for backwards compatibility.
  • imageID - This is the image's ID.  It is the image's associated unique ID value (if one was defined), or otherwise its numeric index.
  • galleryID - This is the gallery's ID.  It is the gallery's associated unique ID value (if one was defined), or otherwise its numeric index.

To use the information in the JSON object, an eval() call must be used on the string.  For example, the following javascript code block could be placed in your HTML page to display an alert every time a new image starts to open:

   <script language="javascript">
   function XMLFlashSlideshow_v4_syncImagesStart(jsonString)
   {
    // This method doesn't return anything...
    var infoObject = eval(jsonString);
    alert('The slideshow has just started to open a new image.  Here is its UniqueID: ' + infoObject.uniqid);
   }
   </script>

  

XMLFlashSlideshow_v4_syncImages(JSONInfoObject:String):void

This method is automatically called in the host page whenever an image has been opened/synced. It is called shortly after the above syncImagesStart method. It allows your page to track the current image that is open in the slideshow. You could use this to display pertinent image-related information in the HTML page, or to track which image is open and store the state in a cookie, etc. Or, you could use a package such as SWFAddress to enable back/forward button browser navigation.

The passed string is a JSON string which evaluates to an object with the following properties:

  • uniqid - This is the standard UniqueID associated with the image.  It is either the gallery's numeric index, or its associated unique ID value, followed by -> and the image's numeric index or its associated unique ID value.  This value can be used for other calls, such as the XMLFlashSlideshow_v4_setImage(uniqid:String) call documented below.
  • uniqidOLD - This is the UniqueID for the image in the old deprecated format (e.g. img_0_5).  It is only included for backwards compatibility.
  • imageID - This is the image's ID.  It is the image's associated unique ID value (if one was defined), or otherwise its numeric index.
  • galleryID - This is the gallery's ID.  It is the gallery's associated unique ID value (if one was defined), or otherwise its numeric index.

To use the information in the JSON object, an eval() call must be used on the string.  For example, the following javascript code block could be placed in your HTML page to display an alert every time a new image has opened:

   <script language="javascript">
   function XMLFlashSlideshow_v4_syncImages(jsonString)
   {
    // This method doesn't return anything...
    var infoObject = eval(jsonString);
    alert('The slideshow has just opened a new image.  Here is its UniqueID: ' + infoObject.uniqid);
   }
   </script>
  

XMLFlashSlideshow_v4_viewReady(currentViewID:String):void

This method is automatically called in the host page whenever a new layout view is opened/displayed.  It allows your page to track which layout view is currently open.  You could use this in conjunction with the above getInitialViewID() or below setLayoutView method to restore a slideshow's layout state when a user returns to a page.

The passed string parameter is the id value of the new view.

For example, the following javascript code block could be placed in your HTML page to display an alert every time a new layout view is opened:

 

   <script language="javascript">
   function XMLFlashSlideshow_v4_viewReady(curentViewID)
   {
    // This method doesn't return anything...
    alert('The slideshow has just opened a new layout view.  Here is its ID value: ' + currentViewID);
   }
   </script>
         

 

Details and Examples for Incoming Calls

Method Name/Signature Description
XMLFlashSlideshow_v4_requestGallery(uniqid:String = "0"):void

This call cannot be made until the XMLFlashSlideshow_v4_notifyReadyForImageSet() outgoing call has been made (see above). Calling this method opens the specific gallery identified by the passed gallery UniqueID. The unique ID can be the gallery's linkage ID, or its numeric index.  For example, the following snippet (which would need to be placed within some other block of code) would open the second gallery:

   <script language="javascript">
   ...
   // Open the second gallery
   XMLFlashSlideshow_v4_requestGallery("1");
   ...
   </script>
       

If you wanted to open a gallery with an ID value of myGallery, you could use the following code:

 

   <script language="javascript">
   ...
   // Open the second gallery
   XMLFlashSlideshow_v4_requestGallery("myGallery");
   ...
   </script>
       

 

Note: The deprecated format which was previously used is gallery_N where N is the numeric index of the gallery.  While this format still works, it is preferable to use the new format of either a simple numeric index or a gallery ID string.

XMLFlashSlideshow_v4_setImage(uniqid:String = "0->5"):void

This call cannot be made until the XMLFlashSlideshow_v4_notifyReadyForImageSet() outgoing call has been made (see above).  Calling this method opens the specific image identified by the passed image UniqueID. For example, the following snippet (which would need to be placed within some other block of code) would open the third image in the second gallery:

   <script language="javascript">
   ...
   // Open the third image in the second gallery
   XMLFlashSlideshow_v4_setImage("1->2");
   ...
   </script>
       

 

If you wanted to open an image with an ID value of myImage within a gallery with an ID value of myGallery, you could use the following code:

 

   <script language="javascript">
   ...
   // Open the second gallery
   XMLFlashSlideshow_v4_setImage("myGallery->myImage");
   ...
   </script>
       

 

Note: The deprecated format which was previously used is img_N_I where N is the numeric index of the gallery and I is the numeric index of the image within the gallery.  While this format still works, it is preferable to use the new format of a gallery index or ID followed by -> and an image index or ID.

XMLFlashSlideshow_v4_setLayoutView(viewID:String = "someViewID"):void Calling this method opens the layout view associated with the passed view ID.  This method is only to be used for changing the current layout view of an already-initialized slideshow.  If you wish to explicitly specify the initial layout view, use the above-described getInitialViewID method.  For example, the following snippet (which would need to be placed within some other block of code) would open the layout view with an ID of specialLayoutView :

 

   <script language="javascript">
   ...
   // Open the layout view with an ID of 'specialLayoutView'
   XMLFlashSlideshow_v4_setLayoutView("specialLayoutView");
   ...
   </script>
         

 

XMLFlashSlideshow_v4_getXML():String

This call cannot safely be made until the XMLFlashSlideshow_v4_notifyReadyForImageSet() outgoing call has been made (see above).  Calling this method returns the full XML document being used for the current slideshow as a string.  This XML document incorporates any external data sources that have been loaded and transformed into the slideshow XML format.  (For more information about the slideshow XML format, see the Developer Reference.)  This method is useful, for example, in creating a dynamic HTML gallery selector: the XML can be requested and then parsed with a tool such as jQuery to find the galleries, then this list used to build a gallery selector that makes XMLFlashSlideshow_v4_requestGallery(...) calls.  The method is also useful for debugging.  For example, the following snippet (which would need to be placed within some other block of code) would display the entire XML document in an alert box.  Note that this may be very large, and to clear it off your screen you may need to press the enter/return key.

 

   <script language="javascript">
   ...
   // Display the slideshow's full XML in an alert box; press enter to clear the box if you can't see the 'dismiss' button.
   alert(XMLFlashSlideshow_v4_getXML());
   ...
   </script>
         

 

 

XMLFlashSlideshow_v4_setPlaying(playing:Boolean):void

Calling this method enables or disables autoplay for a slideshow.  For example, the following snippet (which would need to be placed within some other block of code) would enable autoplay:

 

 

   <script language="javascript">
   ...
   // Enable autoplay for the slideshow (start it playing)
   XMLFlashSlideshow_v4_setPlaying(true);
   ...
   </script>