“Ultimate 3D Carousel With CMS” Documentation by “Valiano” v1.0


“Ultimate 3D Carousel With CMS”

Created: 10/10/2010
By: Valiano
Email: web.power.net@gmail.com

Thank you for purchasing my item. If you have any questions that are beyond the scope of this help file, please feel free to email via my user page contact form here. Thanks so much!


Table of Contents

  1. Gallery Overview
  2. Package Files Overview
  3. Requirements
  4. Installing the gallery
  5. Configuring The Admin
  6. Carousel Javascript Optional Settings
  7. Custom carousel CSS styles
  8. Using API functions
  9. Using the Admin

This is very easy to use jquery carousel plugin, that fully controlled by CMS.
It is very customisible, and has many options that you can set via the CMS, as well as image data.
It can be easily fit to your website layout. You can customize everything, and use your custom buttons, custom preloader, and custom classes. Also, you have a wide javascript API with some useable functions and events that will make your life easier to use the carousel for your needs.
The only limit is your imagination.
The CMS itseld is very intuitive, flexibe and comfortable for use.
I recomend to read this whole documentation about the gallery and CMS before you start using this product.


B. Package Files Overview - top

In the package you have a client side gallery in 2 directories, with sample data and examples, or without.
In every gallery there is the admin folder - the CMS.
The client side is very simple. There is 3 js files that you include in your web page (in js folder) and that's the gallery example html page.
All other components (css, images etc...) comes from the CMS.


C. Requirements - top

Thow the gallery can run from every webserver that supports javascript, you have some minimal requirements for the admin:


Installing the gallery with the CMS is very easy. Basicly, in most cases there is no installation required.
Just upload all the files from the gallery directory to your hosting, and the application will run.
However, if you want to put the admin into another place, you must specify the admin's url in gallery's url_server option.
Example:

$("#gallery").putCarousel({
		url_server:"http://yourdomain.com/admin/gallery.php"});
* To run the CMS simply navigate to "admin" url where you have uploaded it.
Installing the gallery is very simple:
  1. In the <head> section include the 3 javascript files files:
    <script src="js/jquery.js" type="text/javascript"/></script>
    <script src="js/cloud-carousel.min" type="text/javascript"/></script>
    <script src="js/ultimate-carousel.min.js" type="text/javascript"/></script>
    
  2. In he <body> section create a div with some id as a container for the gallery, with or without initial content for loading incication. For example:
    <div id="carousel"></div>
    
    Then add a javascript block with div's ID that will put the gallery content to the div from the CMS.
    <script language="javascript">
    	$("#gallery").putCarousel();
    </script>
    
    That's it. The admin will care of the rest. There are additional confirugations that you can set from the javascript, described in the next chapter.

E. Configuring The Admin - top

After uploading the files, you can configure the Admin for your convinience.
The configuration you set via admin/config/config.php file.


There is a couple of settings that you can use for your convinience, every of them are optional.
  • url_server
  • Url to admin/gallery.php file
  • preset
  • The settings preset from the CMS, if not specified, the first preset will be set.
  • catid
  • Gallery initial category id. You can find the id in the CMS - category caption line in the right
  • event_onInit
  • Event function - when the data has arrived from the admin, but before the images loaded.
    Return arguments:
    arrItems : Array of carousel item data objects. (see the structure below)
  • event_onLoad
  • Event function - after all the images has loaded, and the carousel appeared
    Return arguments:
    container: The container div where the carousel images are located.
    arrItems : Array of carousel item data objects - with image parameter.(see the structure below)
    objCarousel :The carousel object that you can call some API functions from it.
  • event_onItemClick
  • Event function - on some item mouse click
    Return arguments:
    itemData: The item data object (see the structure below).
    isFront : Boolean parameter that tells if the item that envoked the event is a front item.
    image The image html element that envoke the event
  • event_onItemMouseOver
  • Event function - on some item mouse over
    Return arguments:
    itemData: The item data object (see the structure below).
    isFront : Boolean parameter that tells if the item that envoked the event is a front item.
    image The image html element that envoke the event
  • event_onItemMouseOut
  • Event function - on some item mouse out
    Return arguments:
    itemData: The item data object (see the structure below).
    isFront : Boolean parameter that tells if the item that envoked the event is a front item.
    image The image html element that envoke the event
  • event_onFrontItemChange
  • Event function - invoke when front item changes, in other words, every time that the carousel rotates.
    Return arguments:
    frontItemData: The item data object of the front item (see the structure below).
    frontImageThe image html of the front item
    Item Data Object Structure: - Used in all mouse event functions, and in event_onLoad and event_onInit as arrItems
    item.id
    item.title
    item.description
    item.link
    item.filename
    item.image (in event_onLoad only)


    Settings example:
    $("#gallery").putCarousel({
    	preset:"example1",			//the preset ID from "presets" list in the admin
    	url_server:"admin/gallery.php",		//a url to the CMS - gallery.php in admin folder
    	catid:8,				//category id
    	event_onInit:onInit,			//on init event
    	event_onLoad:onLoad,			//on load event
    	event_onItemClick:onItemClick,		//on item click event
    	event_onItemMouseOver:onItemMouseover,  //on mouse over event
    	event_onItemMouseOut:onItemMouseout,	//on mouse out event
    	event_onFrontItemChange:onFrontChange	//on from item change event
    	
    });
    
    - The preset option is a settings preset from the admin. You can set several presets and use them in different pages of the website, for different configuration of the carousel with only one admin.

    - The url_server is an url to gallery.php in the admin folder. By default it admin/gallery.php. If you want to change the admin folder, you can specify the new path in this setting.

    - The catid stands for carousel category id from the CMS. In the CMS you can see the category ID in the right top bar (The bar of category name is located) when you select the category.

    - The events are very usefull carousel feature. With them you can integrate this carousel to your project more efficiently. In the examples folder there is an example that uses those events (example3.html).


    This carousel it totally controlled by the CMS. However, if you feeling that you are missing some important style, you can add your custom styles to every component of the carousel. (please also look at example2.html in the examples page). The styles are:

    .carousel_wrapper Main carousel div
    .carousel_wrapper a.cloudcarousel_link The link that wappes the carousel image
    .carousel_wrapper img.cloudcarousel The carousel image
    .carousel_wrapper .carousel_left_button Left button
    .carousel_wrapper .carousel_left_button_over Left button - mouseover
    .carousel_wrapper .carousel_right_button Right button
    .carousel_wrapper .carousel_right_button_over Right button - mouseover
    .carousel_wrapper .carousel_caption The caption div
    .carousel_wrapper .carousel_description The description div



    H. Using API functions - top

    To use those functions you'll need to get the carousel object from event_onLoad,
    Example:

    //define globally the object			
    var g_gallery = null;
    function onLoad(container,arrItems,objCarousel){	//onLoad event function
    	g_gallery = objCarousel;			//the global object is now the gallery object.
    }
    

    All API functions:
  • g_gallery.rotateLeft()
  • Rotate the gallery left
  • g_gallery.rotateRight()
  • Rotate the gallery right
  • g_gallery.rotateToItem(itemID)
  • Rotate the gallery to some item by item's ID
  • g_gallery.getFrontItem()
  • Get front item data object (look at section F)
  • g_objCarousel.getItemImageUrl(ID,width,height,is_exact)
  • This function get's carousel's image url from the admin with custom size. The image will be cut to that size in the admin, and saves in cache, so next time retrieving that image will be faster.

    Function arguments:
    ID: The item's ID.
    width - Item's maximum or exact width. Specify 0 or -1 for dynamic width
    height - Item's maximum or exact height. Specify 0 or -1 for dynamic height
    is_exact - Boolean parameter (true/false) that indicates if the image will be cut to exact size. Example - exactly 100x100.
    * All this functions syntax you can find in all_options.html file in the examples folder.



    I. Using the Admin - top

    Settings Tab:
    In the settings tab you can set every gallery visual setting.
    There is some defaults that i preset for you hardcoded, so you can restore to defaults, and start over with configuration.
    Just play with the settings, push save, and refresh the gallery to try them on it. Very simple.
    You'll learn them fast. I'd try to give the settings the most understandable names, but if you don't understand something, or you have a diffirent proposal to change some name don't hesitate to write me through my author profile page: http://activeden.net/user/valiano

    Tools Tab:
    In this tab there are several tools that give you another admin capabilities. Currently there is only one very powerfull option, that copies all the pictures from "upload" directory to the gallery. So, if you already have pictures in your server and you want to use them in gallery, just move or copy them into "upload" folder, and press "move all images" button. The images will be moved to selected category.

    Gallery Tab:
    - The gallery panel is very intuitive. On the left side you see all the categories, and onthe right side you see the category images.
    The buttons above every side are related to the items on their side.
    The left "add" button adds categories, and the right "add" button adds images.
    - Also right click is also enabled, and you can do all the operations on the images and categories from the right click.

    Category operations:

  • Add a category
  • Click the "add" button, or "right click -> add new category".
    The category will be added with a default title, you may change the title by selecting
    the category and clicking "edit title" button, or "right click" -> edit title.
  • Delete a category
  • "delete" button, or "right click->delete category". The delete confirm dialog will appear. Note - deleting a category will delete all the picture content in it.
  • Edit category
  • "right click"->edit category or a double click on a category will open the edit dialog. In the dialog you can edit the category title, description and long description.
  • Changing order of categories
  • Just drag and drop the categories up and down. The order is saved on the fly.
    Images operations:
  • Uploading images
  • Press on "upload" button, or "right click" on left side -> upload item to category. You can upload several images at once (multiple upload).
  • Selecting images
  • There are several ways to select images.
    - by clicking on image.
    - by clicking on image and holding control key (add to selection)
    - by clicking on image and holding shift key (select from-to)
    - by drag selection area with the mouse
    - by "right click->select all"
    - by "select all" button at the top
    try it, it's fun.
  • Deleting images
  • Select some images or one image, click on delete button, or "right click -> Delete item/delete selected items"
  • Reorder images
  • select some image, click on some of them, and drag the images to the selected position. After releasing the mouse the order will be saved.
  • Copy/move
  • Select some image, and just drag them to target category.
    Copy/move dialog will appear.
  • Edit title
  • "edit title" button or "right click->edit title", edit box will appear. enter will save the new title.
  • Edit description / link
  • "edit item" button or "right click->edit item", the edit dialog will appear. Press "update" to save the data.
  • Preview image
  • Double click on some item or "right click->preview item" or "preview" button will open the preview dialog.
  • Preview image
  • Double click on some item or "right click->preview item" or "preview" button will open the preview dialog.
  • Preview in browser
  • In preview panel press on "view in browser" button.
    New window with the image will appear.
  • Duplicate image
  • "duplicate" button or "right click->duplicate".



    Once again, thank you so much for purchasing this product. As I said at the beginning, I'd be glad to help you if you have any questions relating to this theme. No guarantees, but I'll do my best to assist.

    Max (valiano user)

    Go To Table of Contents