README.txt in Views Slideshow Xtra 7

README.txt for the Views Slideshow Xtra (VSX) Module 


Overview
--------

The purpose of the Views Slideshow Xtra module is to create an easy way to place HTML elements
(text, links, icons, etc) on top of a Views Slideshow.  The HTML elements are placed in 
overlays 
 overlays, with elements visiblity controlled by setting the  
CSS 'display' property, so that elements are displayed with their corresponding slide.
There are two types of overlays: one that is always present, and another that is
invoked as a popup lightbox.  Note that the lightbox functionality is currently not functional
in the D7 Alpha version.  

The elements are created by entering JSON formatted data in a special multi-value text field for 
each slide node.  Typically, each field value creates a single slide overlay element. 

There is an example implementation of this module at http://drupalanswer.com/vsx7.  This
page has two examples on one page, demonstrating that multiple slideshows may be on a single page.

The Views Slideshow Xtra Example module included as part of this project creates  
a content type and example slide nodes, so you may easily create a working Views Slideshow Xtra
slideshow.


Installation Instructions
-------------------------

1.  Download and extract to your modules directory the following modules:
    colorbox, ctools, libraries, views, views_slideshow, views_slideshow_xtra.

2.  Download the Cycle plugin from http://malsup.com/jquery/cycle/download.html and
    extract into the directory /sites/all/libraries/jquery.cycle.
    All files except jquery.cycle.all.min.js may be deleted.

3.  Download the ColorBox plugin from http://colorpowered.com/colorbox to
    /sites/all/libraries and extract (this will create the child directory
    /sites/all/libraries/colorbox).

4.  Enable the following modules: colorbox, ctools, libraries, views, views ui,
	views_slideshow, views_slideshow_cycle, views_slideshow_xtra.
   
5.  Go to Configuration -> Media: Colorbox and check the "Enable Colorbox load" checkbox
    and save the setting.

6.  If a working example is desired, enable the Views Slideshow Xtra Example module.
    Enabling the module creates an example slide content type. To create example slide nodes,
    go to the path "views-slideshow-xtra-example-nodes", and three example slide nodes will
    be created.


Creating a VSX Slideshow View
-----------------------------

1.  Select Structure => Views and click "Add new view".

2.  Input View name.  Show "Content" of type "Your Slideshow Content Type" ("Views Slideshow Xtra" if 
    configuring a View using the content type created by the VSX Example module).

3.  Leave "Create a page" checked, and select Display form at "Slideshow" of "fields", uncheck "Use a pager", 
    and click "Continue and Edit" to create the View.

4.  Click Fields => add.  Search "image" and check your image field ("Views Slideshow Slide Image"
    if configuring a View  using nodes created by the Views Slideshow Xtra Example module).  Click
    "Add and Configure Fields".  Uncheck "Create a label", and select the appropriate Image style
    (select "None (original image)" if configuring the field from the VSX Example module), and then click
    "Apply (all displays)".

5.  Click Fields => add.  Search for your VSX JSON field ("Views Slideshow Xtra Overlay Elements" 
    if configuring a View using nodes created by the Views Slideshow Xtra Example module)and check it, and click
    "Add and Configure Fields".  Uncheck "Create a label", check "Exclude from display", and then click
    "Apply (all displays)".
    
6.  Click the Title field and remove it.

7.  Save the View and make sure it is functioning as a Views Slideshow by clicking "Update Preview".
    If configurating a View using the slide nodes created by the Views Slideshow Xtra Example module,
    you should have a working slideshow of three slides.

8.  In the Format section, click the Settings link.  In the "Top Widgets" section, check the "Views Slideshow Xtra" 
    checkbox, then in the "Fields" section, check your VSX Overlay field ("Views Slideshow Xtra Overlay Elements" if
    using the content type created by Views Slideshow Xtra Example), and then click "Apply (all displays)".
    
9.  Save the View and make sure it is functioning as a VSX Slideshow by clicking "Update Preview".  If your
    View is using the slide nodes created by the Views Slideshow Xtra Example module, you should have a working VSX
    slideshow with Text and Link overlay elements visible on the slides.

Overlay Element JSON Notation
-----------------------------

Type: Text Element
Example: {"type":"text", "top": 50, "left": 50, "text":"Text Element 1"}

Type: Link
Example: {"type":"link", "top": 100, "left": 200, "text":"Link to Drupal.org", "url": "http://drupal.org"}

Type: Lightbox Link
(Not yet implemented in the D7 Alpha version)


Notes
-----

1. There is an 850 millisecond delay before the overlay elements are displayed.  
This was added to avoid issues with font pixelation in IE that may occur
when text is located in an area where a jQuery Cycle transition takes place.
Eventually the length of this delay will be configurable by slide show and element type.

2. To fine tune your slideshow, you will need to override some of the CSS rules found in 
views-slideshow-xtra.css, located in the module directory.  Don't change views-slideshow-xtra.css,
but rather override its CSS rules as required in your theme's CSS files.

3. Layout of the lightbox fields is controlled by rules in views-slideshow-xtra.css.  The default 
layout has the title across the top and lightbox text and video floated left below the title. You can 
change this by overriding the floats, heights, padding, etc. found in views-slideshow-xtra.css.

4. Whenever the mouse is moved over the slideshow, the show is paused for two seconds.  This is 
done to prevent the situation where a user moves the mouse pointer towards a link and the slide
transitions before the user is able to click the link.  As long as the mouse is moving, the 
slides will not transition for two seconds.
 
5. To put a mask over the slideshow, apply a background image to the div with class 
".views-slideshow-xtra-overlay".