#

### version 1.0.2

Usage Options Methods Objects position Keywords
Basic usage
Advanced usage
Items as links
Full usage
Configuration

1. First extract all files in the same directory.
   - To run ContentFlow you only need : 'contentflow.js', 'contentflow.css' and the 'img' directory.
2. 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.
3. 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>

4. 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.

item
  If you want to use an item as a link, just add an 'href' attribute to the item or it's content. A 'target' attribute will be taken into account.

content
  The actual content of an item. Can be anything.
  If the content element is not an image, beware that the item itself will be scaled and not the content!
caption
  If exists will be used as the caption text of the item.
  By default it is hidden and will be used for the global caption.
  Can contain any HTML content.
  To utilize the caption as a link, just make the whole caption a link (use an a-tag instead of a div-tag) or put a link inside it.
label
  If exists and position element exists, it will be used as the position text label.
  It's great to use the scrollbar as a timeline.

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.

slider
  If exists will show a dragable button on the slider.

position
  If exists will show position label. Defaults to the item number.

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.

1. Copy the file 'ContentFlowAddOn_DEAFULT.js' to 'ContentFlowAddOn_MyAddOn.js'
2. Change the name of the AddOn (first line of code in the AddOn file) to 'MyAddOn'
3. Make the changes you like.
4. 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>

5. 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.

1. Copy the file 'ContentFlowAddOn_DEAFULT.js' to 'ContentFlowAddOn_MyAddOn.js'
2. Change the name of the AddOn (first line of code in the AddOn file) to 'MyAddOn'
3. Make the changes you like.
4. 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>

5. 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.

Generic
Items
Flow interaction
Events
Calculations

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!

These functions will be bound to the ContenFlow object, so 'this' refers to the ContentFlow!
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 !

These functions will be bound to the ContenFlow object, so 'this' refers to the ContentFlow!
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
ContentFlow
Item
Configuration

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)

            }

`