First extract all files in the same directory.
- To run ContentFlow you only need : 'contentflow.js', 'contentflow.css' and the 'img' directory.

Now load the ContentFlow script by adding the following code to the head of your html file:
```
        <script language="JavaScript" type="text/javascript" src="PATH/contentflow.js"></script>
                    
```
Where PATH is the path to the directory where you extracted ContentFlow to.

Create the needed (X)HTML structure. The minimal (X)HTML structure needed is something like this:


        <div class="ContentFlow">
            <div class="loadIndicator"><div class="indicator"></div></div>
            <div class="flow">
                <img class="item" src="someImageFile.jpg" title="Your_Image_Title"/>
                <!-- Add as many items as you like. -->
            </div>
            <div class="globalCaption"></div>
            <div class="scrollbar"><div class="slider"><div class="position"></div></div></div>
        </div>

That's it. Nothing more to do.

To utilize an item as a link just add an href attribute to the item or the content tag like this:


        <div class="ContentFlow">
            <div class="flow">
                <div class="item" href="YOUR_URL"><img class="content" src="someImageFile.jpg"/></div>
            </div>
        </div>

or even


        <div class="ContentFlow">
            <div class="flow">
                <img class="item" href="YOUR_URL" src="someImageFile.jpg"/>
            </div>
        </div>

To be standard compliant just use an anker-tag as the item tag:


        <div class="ContentFlow">
            <div class="flow">
                <a class="item" href="YOUR_URL"><img class="content" src="someImageFile.jpg"/></a>
            </div>
        </div>

Beware: In this case no element within the item may contain any ankors !!!

You can even use the target attribute to open the link in a new window:


        <div class="ContentFlow">
            <div class="flow">
                <a class="item" href="YOUR_URL" target="_blank" ><img class="content" src="someImageFile.jpg"/></a>
            </div>
        </div>

Basic principles

The direct usage of an image tag as an item is a simplified form of the default HTML structure and will be converted internally.


        <img class="item" src="someImageFile.jpg" title="Your_Image_Title"/>

corresponds to


        <div class="item">
            <img class="content" src="someImageFile.jpg"/>
            <div class="caption">Your_Image_Title</div>
        </div>

Not only images can be used as a content, but basicly any HTML elements you like.

ContentFlow is very flexible, so if you don't like having the loadIndicator, the globalCaption or the scrollbar just remove them. ContentFlow will utilize them if it detects them.
So the very basic HTML structure is something like this:


        <div class="ContentFlow">
            <div class="flow">
                <img class="item" src="someImageFile.jpg"/>
            </div>
        </div>

What about styling?

If you want to change some styling you can do this globaly. Just rename the file 'mycontentflow.css.example' to 'mycontentflow.css', make the changes you like and you are ready to go.
For example, if you have a white background, I already have done the work for you. Just use the 'white' AddOn. To utilze it just download it, extract it into the same directory as 'contentflow.js' and add the load attribute to the script tag:


        <script language="JavaScript" type="text/javascript" src="ContentFlow/contentflow.js" load="white"></script>

Configuration

It's quite easy to change the configuration of ContentFlow. If you just want to fiddle with the configuration the fastest way is to create a new ContentFlow object in javascript:


        <script>
            var myNewFlow = new ContentFlow('myFantasicFlow', { OPTION_1: value_1, OPTION_2: value_2, ... , OPTION_N: value_N } ) ;
        </script>

So let's say you want to disable the reflection (set reflectionHeight to 0) and don't want the flow to wrap around at the end (set circularFlow to false). You have to give the ContentFlow tag an id (let's call it 'myFantasicFlow') and insert the following script tag somewhere in your page:


        <script>
            var myNewFlow = new ContentFlow('myFantasicFlow', { reflectionHeight: 0, circularFlow: false } ) ;
        </script>

Files

mycontentflow.css.example: This is an example file which will help you to style your ContentFlow globaly. Rename it to 'mycontentflow.css' to utilize it.
ContentflowAddOn_DEFAULT.js & ContentflowAddOn_DEFAULT.css: This are example files from which you can build your own AddOn.

Script tag

By adding the 'load' attribute to the script tag you can load one or more AddOn. The AddOns have to be given in the form of a space separated list and are loaded in the same order as given.


        <script language="JavaScript" type="text/javascript" src="PATH/contentflow.js" load="SomeAddOnName SomeOtherAddOnName" ></script>

Where PATH is the path to the directory where you extracted ContentFlow to.
'contentflow.js' is a compressed (using yuicompressor) version of 'contentflow_src.js'. If you run in any problem with the compressed version, just change 'contentflow.js' to 'contentflow_src.js' (and drop me note).

(X)HTML

This code example shows all (X)HTML elements and element attributes ContentFlow knows about:


        <div id="myFantasticFlow" class="ContentFlow" useAddOns="AddOns1 AddOn2 ...">
            <div class="loadIndicator"><div class="indicator"></div></div>
            
            <div class="flow">
                <div class="item" href="URL" target="TARGET" >
                    <img class="content" src="someImageFile.jpg" href="URL" target="TARGET" /> 
                    <div class="caption">foobar</div>
                    <div class="label">Slider Label</div>
                </div>
                (Add as many items as you like.)
            </div>

            <div class="globalCaption"></div>
            <div class="scrollbar">
                <div class="preButton"></div>
                <div class="nextButton"></div>
                <div class="slider"><div class="position"></div></div>
            </div>
        </div>

The 'loadIndicator', 'caption', 'label', 'globalCaption', 'scrollbar', 'preButton', 'nextButton', 'slider and 'position' elements are optional. ContentFlow will auto detect and utilize them if they exist.

ContentFlow: Main ContentFlow wrapper. All elements of class 'ContentFlow' will be initialized.
If style attribute 'height' is set, maxItemHeight will be set accordingly.
If the attribute 'useAddOns' is given only the listed AddOns will be used for this ContentFlow.
flow: Wrapper around all flow items.
If style attribute 'height' is set, maxItemHeight will be set accordingly.
loadIndicator
: If exists will show a loading indicator, while images are loaded.
globalCaption
: If exists and caption element of active item exists will show the caption of the active item.
scrollbar
: If exists will show a clickable scrollbar.
preButton
: This element can be anywhere within the ContentFlow. If exists it will fire the onclickPreButton method.
By default it will move the flow to the previous item.
nextButton
: This element can be anywhere within the ContentFlow. If exists it will fire the onclickNextButton method.
By default it will move the flow to the next item.

Configuration

You can configure each ContentFlow independently or globally. Take a look at the configuration and options descriptions for an explanation.

If you want to adjust ContentFlow to your needs you have two possibilities. First you can use an AddOn or you can use a runtime configuration.

AddOn configuration

I think, that is the more convenient method.

Copy the file 'ContentFlowAddOn_DEAFULT.js' to 'ContentFlowAddOn_MyAddOn.js'
Change the name of the AddOn (first line of code in the AddOn file) to 'MyAddOn'
Make the changes you like.
Add the 'load' attribute to the script-tag which loads ContentFlow. Now add any AddOns you would like to use as a space separated list.
It should now look like this:
```
    <script language="JavaScript" type="text/javascript" src="PATH/contentflow.js" load="MyAddOn" ></script>
            
```
Reload your page :-)

Runtime configuration

Create a new Object from the Class ContentFlow and pass the element containing the flow as its parameter, like this:


    <script language="JavaScript" type="text/javascript">
        var myNewFlow = new ContentFlow('myFantasicFlow'[, OPTIONS ]);
    </script>

OPTIONS: is an optional configuration data object where co can define the options.

Configuration

If you want to adjust ContentFlow to your needs you have two possibilities. First you can use a AddOn or you can use a runtime configuration.

AddOn configuration

I think, that is the more convenient method.

Copy the file 'ContentFlowAddOn_DEAFULT.js' to 'ContentFlowAddOn_MyAddOn.js'
Change the name of the AddOn (first line of code in the AddOn file) to 'MyAddOn'
Make the changes you like.
Add the 'load' attribute to the script-tag which loads ContentFlow. Now add any AddOns you would like to use as a space separated list.
It should now look like this:
```
    <script language="JavaScript" type="text/javascript" src="PATH/contentflow.js" load="MyAddOn" ></script>
            
```
Reload your page :-)

Runtime configuration

Create a new Object from the Class ContentFlow and pass the element containing the flow as its parameter, like this:


    var myNewFlow = new ContentFlow('myFantasicFlow'[, OPTIONS ]);

OPTIONS: is an optional configuration data object where you can define the options.

useAddOns := string | array (default: all): Addons this ContentFlow should use (all, none, [AddOn1, ... , AddOnN])
loadingTimeout := int (default: 30000): Grace time in milliseconds for images to load.
circularFlow := bool (default: true): Should the Flow wrap around?
verticalFlow := bool (default: false): Will turn the ContentFlow 90 degree counterclockwise.
This will automatically swap calculated positions and sizes where needed. You do not have to adjust any calculations or sizes. Should work with any AddOn outof the box.
visibleItems := int (default: 0): Number of items to show on either side of the active Item. If set to '0' it will be set to the square root of the number of items in the flow.
endOpacity := float (default: 1): The opacity of the last visible item on either side. The opacity of each item will be calculated by the 'calcOpacity' function.
startItem := string | int (default: center): Active Content item to start with. Can be either a position keyword or an integer.
scrollInFrom := string | int (default: pre): Flow will start scrolling on load from this item. Can be either a position keyword, "none" or an integer. If set to "none" the flow will not scroll in.

flowSpeedFactor := float (default: 1.0)

A flowSpeedFactor > 1 will speedup the scrollspeed, while a factor between 0 and 1 will slow it down

flowDragFriction := float (default: 1.0)

Determines how hard it is to drag the flow.
If set to '0' dragging of the flow is deactivated.

scrollWheelSpeed := float (default: 1.0)

Scales by how many items the flow will be moved with one usage of the mousewheel.
Negative values will reverse the scroll direction.
If set to '0' scrolling with the mouse wheel is deactivated.

keys := object (default: see below)

Defines the keyCodes and the functions, which are triggerd on a keydown event within the ContentFlow. All defined functions are bound to the ContentFlow object.
To disable this functionality set keys = {} (empty object).
Default setting:


    {
        13: function () { this._onclickActiveItem(this._activeItem) }, // return/enter key
        37: function () { this.moveTo('pre') },         // left arrow
        38: function () { this.moveTo('visibleNext') }, // up arrow
        39: function () { this.moveTo('next') },        // right arrow
        40: function () { this.moveTo('visiblePre') }   // down arrow
    }

reflectionHeight := float (default: 0.5): Set the size of the reflection image relative to the original image
reflectionGap := float (default: 0.0): Set the size of the gap between the image and the reflection image relative to the original image size
reflectionColor := string (default: transparent): Set the "surface"-color of the reflection. Can be "none", "transparent", or #RRGGBB (hex RGB values)
If set to 'overlay' the image given by the option 'reflectionOverlaySrc' will be lain over the reflection.
scaleFactor := float (default: 1.0): Factor by which the item will be scaled.
scaleFactorLandscape := float | string (default: 1.0): float := Factor to scale content images in landscape format by.
string := if set to 'max' the height of an landscape image content will be set to the height of the item.
scaleFactorPortrait := float | string (default: 1.0): float := Factor to scale content images in portrait format by.
string := if set to 'max' the width of an portait image content will be set to the width of the item.
fixItemSize := bool (default: false): Fixes the item size, to the calculated size. No adjustments will be done. Images will be croped if bigger.
maxItemHeight := int (default: 0): Maximum item height in px. If set to a value greater than '0' the item size will be calculated from this value instead relative to the width of the ContentFlow.
relativeItemPosition := string (deafult: top center): Position of item relative to it's coordinate.
It can contain the keywords top/above, bottom/below, left, right and center.
So by default the item will be placed above the coordinate point and centered horizontally.
If set this option overrides the calcRelativeItemPosition option!

onclickInactiveItem := function(obj item): called if an inactive item is clicked.
onclickActiveItem := function(obj item): called if the active item is clicked.
onMakeInactive := function(obj item): called if the active item becomes an inactive item.
onMakeActive := function(obj item): called if an item becomes the active item.
onMoveTo := function(obj item): called each time a new target is set i.e by calling the moveTo method.
onReachTarget := function(obj item): called if the target item becomes the active item.
onclickPreButton := function(event event): called if the 'pre' button item is clicked.
onclickNextButton := function(event event): called if the 'next' button item is clicked.
onDrawItem := function(obj item): called when ever an item is redrawn. Use with caution, because this method is easily called many thousend times !

calcStepWidth := function(float diff): called to set the calculation function of the width of each step to get the next position of the flow.
The function will be bound to the ContenFlow object, so 'this' refers to the ContentFlow!
float 'diff' := targetItemPosition - currentPosition returns: float
calcSize :=function(obj item): called to set the calculation function of the size of a visible item
returns an object of type size := {width: w, height: h}
calcCoordinates := function(obj item): called to calculate the position of an item element within the flow
returns an object of type position := {x: x, y: y}
calcRelativeItemPosition := function(obj item): called to calculate the position of an item relative to it's coordinates
Beware: this function will be overridden by the 'relativeItemPosition' option!
returns an object of type position := {x: x, y: y}
calcZIndex := function(obj item): called to set the calculation function of the z-index of each item. The z-index is only valid within the flow itself.
returns: int z (-32768 ≤ z ≤ 32768)
calcFontSize := function(obj item): called to set the calculation function of the relative font-size of an item
returns: float fs (0.0 ≤ fs)
calcOpacity := function(obj item): called to calculate the opacity of each item.
returns: float o (0.0 ≤ opacity ≤ 1.0)

Methods

The following object methods are public.

setConfig(obj OPTIONS): called to set options after object creation
getItem(int index): returns the 'item' object at given index
getActiveItem(): called to get the currently active item. returns the 'item' object of the active item.
getNumberOfItems(): called to get the number of items currently in the flow
moveTo(int index | float pos | string keyword | obj item): called to scroll to item.
'index' := scroll to item with index 'index'
'pos' := scroll to position 'pos'
'keyword' := scroll to position given by position keyword 'item' := scroll to item
resize(): called to reinitialize the size of the flow items, after the size of the flow has changed.
Is called if window is resized.
addItem(DOMnode element, int|string index): called to add a new item 'element' to the flow at the position index. The element has to be a valid item element. So it must have at least this structure:
<div class="item"><img class="content" src="url/to/image"/></div>
The index has to be an integer or one of the strings 'first', 'start', 'last' or 'end'.
returns: int index (index position of added item)
rmItem([int index]): called to remove an item from the flow. If the parameter index is given the element at the index position 'index' will be removed, else the currently active item will be removed. returns: DOMnode el (cleaned item node)

position keywords

'start', 'first': first item
'end', 'last': last item
'middle', 'center': item in the middle
'pre', 'previous', 'left': previous item
'next', 'right': next item
'visible', 'visiblePre' 'visibleLeft': leftmost visible item
'visibleNext', 'visibleRight': rightmost visible item

Where ever you can use a position keyword you can also use an integer for an exact position. A sanity check will be done automatically.

ContentFlowGlobal is a globaly accessible object.


        {
            Flows   := [
                          ContentFlowObj_0,
                          ContentFlowObj_1,
                          ...
                       ], 

            AddOns  := {
                         AddOnName: AddOnObj,
                         ...
                       },

            Browser := {
                        Opera := bool,
                        IE := bool,
                        IE6 := bool,
                        IE7 := bool,
                        IE8 := bool,
                        WebKit := bool,
                        iPhone := bool,
                        Chrome := bool,
                        Safari := bool,
                        Konqueror := bool,
                        Konqueror4 := bool,
                        Gecko := bool,
                        Gecko19 := bool
                       },

            getAddOnConf := function (AddOnName),
            
            setAddOnConf := function (AddOnName, confObj)

        }

This is the basic structure of a ContentFlow object.


        {
            Container       := DOM-Element      // DOM element of the '.ContentFlow' element
            Flow            := DOM-Element      // DOM element of the '.flow' element
            Scrollbar       := DOM-Element      // DOM element of the '.scrollbar' element
            Slider          := DOM-Element      // DOM element of the '.slider' element
            items           := Array            // [ item0, item1, ... , itemN ]
            conf            := conf obj         // object containing the configuration options
            Browser         := obj              // ContentFlowGlobal.Browser
        }

The options can be passed to the ContentFlow on creation, by the setConfig method or by an AddOn in the form of a data object.


        {
            option1: value,
            option2: value,
            .
            .
            .
            lastOption: value   // beware: last option must not end with a comma !
        }

An 'item' object represents an item within the ContentFlow and has the following structure.


        {
            element             := DOM-ELEMENT  // DOM element of the item
            pre                 := item obj     // the previous item
            next                := item obj     // the next item
            content             := DOM-ELEMENT  // DOM element of the item content
            caption             := DOM-ELEMENT  // DOM element of the item caption
            label               := DOM-ELEMENT  // DOM element of the item label
            index               := int          // index of item
            position            := float        // position on the internel position axis  
            relativePosition    := float        // relative position of item 
                                                //     (-visibleItems ≤ relativePosition ≤ visibleItems)
            relativePositionNormed  := float    // normed relative position of item 
                                                //     (-1 ≤ relativePosition ≤ 1) 
            side                := int          // left,center,right (-1,0,1)
            size                := size obj     // size object as returned by calcSize 
                                                //     {width: float, height: float} (0 ≤ width, height ≤ 1)
           
        }

version 1.0.2

Basic principles

What about styling?

Configuration

Files

Script tag

(X)HTML

Configuration

AddOn configuration

Runtime configuration

Configuration

AddOn configuration

Runtime configuration